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This publication describes the internal logic of the 
nonresident access metnods used in TSS/360. (The 
facility which controls most conversational input/output 
in TSS/360, t ne resident terminal access method (RTAM) is 
part of the resident supervisor and is described in IBM 
S ystem/360 Time Sharing System: Resident Supervisor 
Program Logic Manual , GY 2 8- 2 01 2.) 

The nonresident access metnods are; 

• The virtual access methods (VAM) , used to store and 
retrieve page-organized data located on direct access 
devices, and including the virtual sequential CVSAM) f 
virtual index sequential (VISAM) , and virtual 
partitioned (VPAM) access methods. 

• The sequential access methods (SAM), used to access 
OS/360-or iented data sets on tape or direct access 
devices, and including the basic sequential (BSAM) 
and queued sequential (QSAM) access methods. 

• The multiple sequential access method (MSAM) , used 
for efficient input/output with unit record 
equipment . 

• A facility, IOHEv, which allows a user to provide his 
own access met hoi with < private device. 

• The terminal access method (TAM) , which allows 
input/output with specific terminals. 

• A Terminal Task Control module which provides task 
control for multitermina 1 task (MTT) applications. 

For each access method, an overview, routine 
descriptions, and flowcharts are provided. 

This material is intended for persons involved in 
program maintenance, and system programmers who are 
altering the program design. It can be used to locate 
specific areas of the program, and it enables the reader 
to relate these areas to the corresponding program 
listings. Program logic information is not necessary for 
the use and operation of the program. 
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This publication describes the access 
methods in T5S/M0 I except for the resident 
terminal access method*). It can be read 
selectively for a general under standing of 
a particular access method, or it can be 
used as a guide to more detailed 
information in an object program listing of 
a particular access method object module. 
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methods are grouped in one section. 
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PART I 
ACCESS METHOD FOR BSAM, MSAM, TAW AND IOREQ 



SECTION 1: 



INTRODUCTION 



The data management access methods for 
IBM Time Sharing System/360 (TSS/360) 
include the routines, control blocks, and 
work areas that receive or transmit data 
from or to I/O devices. Part I describes 
data management access methods: 

1. Basic Sequential Access Met nod (BSAM) 

2. Multiple Sequential Access Method 
CMS AM) 

3. Resident Terminal Access Method (RTAM) 
- Overview only 

4. Terminal Access Method CTAM) 

5. I/O Request CIOREQ) 

The routines in eacn of the access 
methods, although similar in operation, 
differ in these ways: 

• BSAM routines enable the user to access 
data at the READ/WRITE macro instruc- 
tion level. BSAM processes sequential 
data sets that reside on magnetic-tape 
or direct access devices. BSAM data 
sets are compatible (except for the two 
limitations indicated in the BSAM over- 
view) whether created under IBM System/ 
360 Operating System, referred to as 
Operating System/360 (OS/360), or under 
TSS/360. Both data sets can oe pro- 
cessed by OS/360 BSAM and TSS/360 BSAM. 

• MSAM routines allow tne user to process 
logical records at the GET/PUT macro 
instruction level for the 2540 card 
reader/punch and 1403 printer. MSAM 
differs from BSAM in that the channel 
command words (CCWs) used to perform 
the I/O operations on the above men- 
tioned devices are command chained, 
significantly reducing the interruption 
processing overhead. MSAM can be emp- 
loyed by any user; however, device 
management restricts tne use of unit 
record equipment to privileged users. 



• RTAM routine 
are located 
supervisor, 
detailed des 
tion of RTA& 
mary PLK , GC 
Supervisor P 
cation descr 
the virtual 
to other ace 
initiates mu 
and sets up 



s, as the name suggests, 
mainly in the resident 

For the logic flow and 
criptions of the major por- 
, see the System Logic Sum- 
28-2009 and the Resident 
LM, GY28-2012. This publi- 
ibes Terminal Task Control, 
storage routine, analogous 
ess methods routines, which 
lti-terminal tasks (MTT) 
read, write, and polling 



control blocks for RLADQ, WRITLV, 
FINDQ, FREEQ, and CLEARQ macros issued 
by the MTT user. 



• TAm routines restrict nonprivileged 
user programs to accessing data using 
the GATE macro instructions, and allow 
privileged programs to access data at 
the RLAD/WRITE macro instruction level. 
TAM processes sequential data sets that 
reside on specified communication 
terminals. 



• IOREQ routines permit the user to 
access data, from any device, at the 
channel command word (CCW) level. The 
user must, however, be privileged to 
have access to these IOREQ routines for 
unit record equipment. 

This section provides an introduction to 
the access methods, the user's I/O macro 
instructions, the common control blocks, 
and contains an overview of BSAM, MSAM, 
TAM, and IOREQ. Sections 2, 3, 4, and 5 
discuss details of the access methoa rou- 
tines 8 Open, Read/write, Posting and Close 
phases. Section 6 discusses routine's pri- 
marily designed for use with BSAM. 



Lintcage to the Access Methods routines 

Problem programs, as well as IBM-writtem 
system programs, may, directly or indirect - 
Ly, use the four access methods (BSAM, 
MSAM, TAM, and IOREQ), therefore privileged 
ma nonprivileged programs may link to 
these access methods. The access routines 
are called upon by I/O macro instructions 
that are in source programs. During lan- 
guage processing, the I/O macro Instruc- 
tions are expanded into code that links to 
ana passes parameters to appropriate access 
method routines. The DCB, DFTRMENT, and 
DCBD macro instructions do not link to 
access methods routines but complete their 
function during assembly. Expansion of the 
DCB ana DFTRMENT macro instructions only 
build control block tables. The DCBD macro 
instruction inserts a dummy control section 
at the place the macro instruction is 
encountered. 

Privileged programs use Type-1 linkages 
to the privileged access method routines; 
nonprivileged programs use the ENTER 
mechanism. See IBM System/360 Time Sharing 
System: Task Monitor Program Logic Manual , 
GY-28-2041, for an explanation of ENTER. 
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Note: Numbered boxes refer to the accompanying description under Access Method Phases. 
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Access Method Phases for BSAM, MS AM, TAM f and IOREQ 



'j T r l ^ri. i v ^ttiod Phase:? 

Each of the BSAM, MSA1»j, TAM or IOREQ 
access methods may be presented in four 

phases, illustrated in Figure 1. 

Here are some preliminary notes on each 
of the four phases. The numoers in paren- 
theses correspond to tnose circled in 
Figure 1, 

Open Phase : Details are presented in Sec- 
tion 2 of this jart. 

CD If a user desires transmission of 
data to or from an I/O device, he must ini- 
tially use the OPEN macro instruction in 
ft is program. 

(2) The OPEN macro instruction calls the 
open routines that prepare the I/O devices, 

control blocks, and the data set for furth- 
er processing. 

Kead/Write Phase : Details are presented in 
Section 3. 

(3) After completion of the OPEN rou- 
tines, aata may be transmitted by using the 
READ/WRITr, macro instructions. 



(4) These call the READ/WRITE routines 
that build CCWs in the IORCB. 

(5) Tne resident supervisor is requested 
to execute the channel commands via an IOC- 

AL SVC 



Note : The reaa/write ph 
READ/WRITE or GET/PUT le 
tions where the specific 
READ/WRITE or GET/PUT ie 
tions are listed in Tabl 
macro instructions read 
device. WRITE or PUT ma 
either write data to an 
control information to t 



ase is initiated by 
vel macro ins true- 
access method 
vel macro instruc- 
e 1. READ or GET 
data from an I/O 
cro instructions 
I/O device or send 
he control unit* 



Posting Phase : 
Section 4. 



Details are presented in 



(6) After an I/O operation has been com- 
pleted, an I/O interruption occurs which 
results in the storage of, I/O status infor- 
mation and the IORCB at fixed locations in 
the interruption storage area (ISA). 

(7) The posting routines obtain control, 
via the task monitor, after the resident 
supervisor receives the interruption, with 
all other task interruptions masked off. 
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Table 1, 



BSAM, MSAM, TAM and IOREQ 
READ/WRITE and GET/PUT Level 
Macro Instructions 



| READ Macro 
Access Method j Instruction 



BSAM 


|READ 
j 


MS AM 


|GET 

i 


TAM 
(privileged) 


1 

|READ 
1 



1 

TAM j GATRD 

(nonprivileged) j 

t 
IOREQ | VCCW , IOREQ 

X . . 



WRITE Macro 
Instruction 

WRITE 

PUT 

WRITE 

GATWR 

VCCW, IOREQ 

— . _ — i 



C8) These posting routines record whetn- 
er the I/O operation had a normal or 
abnormal completion. 

(9) The posting routines post the 
results in a DEB and a DECB. 



Note ; Error retry and recovery is 
attempted by the system, if the I/O comple- 
tion was abnormal. (IOREQ POSTING does not 
have error retry or recovery routines.) 
The posting routines return control to the 
task monitor which returns control to the 
interrupted program by loading the old I/O 
VPSW. Consequently, the posting processing 
is transparent to data management routines 
except for the altered DEB and DECB, The 
CHECK macro instruction in the user's pro- 
gram waits for and checks completion of the 
I/O operation that is posted in the DECB. 
(MSAM does not have a CHECK macro instruc- 
tion, DOMSAM performs the functions of the 
CHECK macro for MSAM. GET/PUT provides 
return codes which indicate the completion 
status of the requested operation.) 



Close Phase : Details are presented in Sec- 
tion 5. 

(10) When the user has completed proces- 
sing his data set he issues a CLOSE macro 
instruction. 

Notes When the MSAM user has completed 
processing his data group he may issue a 
FINISH macro instruction prior to the CLOSE 
macro instruction to empty or truncate the 
last buffer and test the result of all out- 
standing I/O. This is preferable to simply 
issuing CLOSE since the task is permitted 
to continue as the I/O operation queue. 

(11) CLOSE calls the close routines 
which will reset/release control blocks and 
complete data set processing. 



Macro I nstructions 

To communicate with the access methods, 
specific I/O macro instructions in the 
user's program are required for BSAM, MSAM, 
TAM and IOREQ Csee Table 2). 

All I/O macro instructions available for 
each of the access methods are in Table 3. 
For more details, see Assembler User Macro 
Instructions . 



Control Blocks 

The list below indicates the control 
blocks that are within the user's program 
and access method storage; BSAM, MSAM, TAM, 
and IOREQ require that all these control 
blocks be generated if the access methods 
are to function. Additional control blocks 
are described later, under the access 
methods to which they are related. 

Dynamically Built or 
Assembly Generated SYSGEN Generated System 
Control Blocks Control Blocks 





SDAT 




SDT 


DCB 


JFCB 


♦DECB 


DEB 




IORCB 



♦ In MSAM the DECB is generated at open 
time. 

Control blocks are generated either in 
the user's program area or in the access 
method area. 

USER'S PROGRAM AREA : The following control 
blocks are generated in the user's program 
area. 

Data Control Block (DCB) : The DCB is 
generated during assembly by a DCB macro 
instruction and serves as a basic communi- 
cations area for I/O operations. It is 
used to maintain information such as data 
set organization, attributes of data set 
buffering information (used in data set 
processing) , and addresses of special exit 
routines . 



Data Event Control Block (DECB) 
is generated during assembly by 
WRITE macro instruction (except 

and serves as an I/O status-ref 
for I/O operations. It is used 
information such as: state of 
of an I/O operation, type of op 
viously issued, CSW information 
that indicate, to the user prog 
tions on ending the I/O operati 



: The DECB 
a READ/ 
for MSAM) 

erence block 
to store 

completion 

eration pre- 
and codes 

ram, condi- 

on. 



ACCESS METHOD AREA : The following tables 
and control blocks are generated in the 
access methods area. 
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Table 2. BSAM f MSAM, TAM, and IOREQ I/O 
Macro Instructions Required for 

I/O Operations 

.^g— — _____ . - , — j 



Table 3. BSAM, MSAM, TAM, and IOREQ Hdcn 
Instxuctions 



| I/O Macro 
| Instruction 
j.__ _ 



I DCB 



1 OPEN 



1 GET/PUT 



I READ/WRITE* 



1 CHECK 



! CLOSE 
I 



IDCBD 



Explanation 



Required prior to open phase; 

reserves space in user's 
program for the data control 
block (DCB), which is basic 
communication area for I/O 
operations. 

Required to start open phase, 
links to open routines to 

open the DCB* 

Required to initiate 
transmission of data . 
Applicable only to MSAM« 

Required to initiate 
transmission of data; 
reserves space for the data 
event control block (DECB) , 
which contains status of I/O 
operations; links to 
read/ write routines that 
build CCWs in the !ORCB f and 
causes the commands to be 
executed by issuing the IOCAL 
SVC. 

Required under BSAM, TAM f and 
IORBQ to test I/O operation 
associated with the DECB; 
waits for and checks 
completion of I/O operations 
that are posted in the DECB; 
for I/O normal completion 
returns to problem program; 
for exception I/O completion 
exits to the routines 
specified in the DCB. 

Required to disconnect data 
set from user's program; 
links to close routines that 
complete control blocks. 

Required if user accesses the 
DCB fields; it provides the 
dummy control section CDSECT) 
which contains all symbolic 
names used to reference 
information in a DCB. 



H 



. _ .-..__„____. „ _„____ — . — „„. 

j *Ref er to Table 1 for listing of specific 

I READ /WRITE macro instructions. 

| READ/WRITE macro instructions at 

| assembly time either generate space for 

| a DECB CS and L form) or refer to an 

I existing DECB (E form) ; MSAM has no 

| READ/WRITE macro. 



I0R£Q 



Used in 
Common 



DCB 
DCBD 

OPEN 
CLOSE 



BSAM 



READ 

WRIT.i 
CHECK 

GETPOOL 

GETBUF 
FREEBUF 
FREEPOOL 
MOTE 

pojwt 

BSP 

FEOV 

CNTKL 

CLOSE 

CTYPE^T) 
DQDECB 



MSAM 



GET 

PUT 

SETUR 

FINISH 



TAW 



READ* 

WRITE* 
CHECK 

DFTRMENT 



IOREQ 



vccw 

CHECK 



♦In TAM f only privileged programs may 
issue the READ/WRITE macro instructions. | 
Nonprivileged programs issue GATRD/GATWRf 
macro instructions. j 



Symbolic Device Allocation Table (SPAT) ; 
The SDAT wnicfc is initialized by devicr 

management resides in public virtual 
storage and prowides information on the 
status and characteristics of each allocat- 
abie I/O device in the system- The SDAT 
contains information on the symbolic device 
address f model code f device code, device 
class and unit type. 



Job File Control Block CJFCB) : The JFCB is 
constructed for a data set by the DDEF rou- 
tine from information in a DDEF command or 
macro instruction. The information in the 
JFCB is used to complete the DCB during 
execution of the OPEN macro instruction. 
The JFCB contains information defining the 
data set attributes, information on where 
the data set is located f and pointers to 
other JFCBs in the task. 

Note: The data set organization must be 
specified in the DDEF command for IOREQ. 

Data Extent Block (DEB) s The DEB is con- 
structed at OPEN time for a given dat set 
and serves as a data set reference block 
for I/O operations. The DEB is used to 
store information such as volume locations f 
device and data set attributes, pointers to 
other control blocks associated with the 
data set, and pointers to DECBs that have 
not been checked. 
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I/O Request Control Block (IORCB) : The 
10RCB is constructed at READ/WRITE time and 
serves as a control reference block for I/O 
operations. It contains the CCWs that con- 
trol the I/O operation and may contain 
either the I/O data buffer, or a pointer to 
the I/O data buffer. 

I/O Statistical Data Table (SDT) ; For each 
device the SDT contains maximum retry thre- 
sholds which are used in certain error 
processing. 



BSAM OVERVIEW 

BSAM comprises those instructions, con- 
trol blocks and data areas which allow for 
limited data set interchange between TSS/ 
360 and OS/360. CTSS/360 BSAM will not 
support the OS/360 direct access split 
cylinder format and will not deblock reco- 
rds provided by OS/360 QSAM. ) 

With tape input and output, BSAM sup- 
ports either EBCDIC symbols and the stan- 
dard IBM label and record formats or the 
print symbols and label and record formats 
of the American National Standard Insti- 
tute. The latter print symbols standard is 
officially the American National Standard 
Code for Information Interchange X3. 4-1968 , 
and is referred to herein as ASCII* The 
latter label and record formats standard is 
officially the American National Standard 
Magnetic Tape Labels for Information Inter- 
change, X3. 27-1969, and the format is 
referred to herein as American National 
Standard. TSS/ 360 processing is in EBCDIC 
and standard IBM format; when the user spe- 
cifies the ASCII option as a parameter of 
the DDEF command, BSAM provides a conver- 
sion interface between ASCII and EBCDIC 
symbols and American National Standard and 
standard IBM formats. 

The access methods descriptions pre- 
sented in this manual do not include the 
DDEF command, which performs some preli- 
minary open functions for BSAM. The Open 
Common and Open BSAM routines oversee the 
completion of the necessary open functions. 

The DDEF command contains such informa- 
tion about the data set as its name, volume 
residence, organization, and type of device 
used. The DDEF command causes the building 
of the job file control block CJFCB) , over- 
sees initial device allocation and mounting 
and allocates space for data sets on direct 
access storage devices. 

By macro instruction, the user will be 
linked to the Open Common routine- This 
routine performs those open functions which 
are common to all the TSS/360 access 
methods. These functions basically are: 



• Finding the JFCB in the system. 

• Filling in the data control uirck (DCS, 
with information from the JFCB- The 
user is thus able to specify, l i,f a 
particular run, many data organization 
and hard ling opt ions which may not be 
known at assembly time. 

• Ensuring that only privileged programs 
use privileged data sets. 

• Checking for conflicts between user 
indicated options and control block 

data . 

• Getting a page of storage to be used 
later for input/output request control 
blocks (lORCBs). 

For BSAM, Open Common links to BSAM 

Open. At this point, the JFCB and DCB have 
becjn constructed, a data extent block 
(DEB), the primary control block used by 
the Read/Write routines for such informa- 
tion as the device type, error statistics, 
outstanding IORCBs , and the queue of 
unchecked I/O requests, is still required. 
BSAM Open f s main function is the building 
of this DEB in protected storage so that it 
cannot be destroyed or changed by the user 
program. To build the DEB, linkage is made 
to the Build Common DEB routine or to the 
Build DA DEB routine; the choice depends on 
device type. 

DA Open is used to complete open proces- 
sing for direct access devices while Tape 
Open is used to complete the open process 
for tape. Both DA Open and Tape Open call 
the appropriate label processing routines 
to process user and data set labels. Label 
information such as record length can be 
used to modify the DCB. 

The labeling routines available in BSAM 
are Tape Label Processor, which has separ- 
ate entry points for input header, output 
header, input trailer, and output trailer 
labels, DA Input User Label Processor, and 
DA Output User Label Processor. 

Where ASCII-encoded tapes have been spe- 
cified, the ASCII Translation and Conver- 
sion routine provides ASCII -to- EBCDIC tran- 
slation on tape input and EBCDIC-to- ASCII 
translation on tape output. 

Four macro instructions are provided to 
obtain buffer space: GETPOOL, GETBUFF, 
FREEPOOL, and FREEBUFF* 

After his data sets have been openea, 
the user will normally access data by means 
of a READ or WRITE macro instruction, tci- 
lowed (not necessarily immediately) by a 
CHECK instruction to ensure complete and 
correct I/O termination. The actual ter- 
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ounation of the I/O operation will cause an 
interruption, at which point the Supervisor 
will link to the SAM Posting and Error 

Hetry (SPER) routine whicn runs with ail 
interruptions disabled. Here the I/O com- 
pletion code is posted into the DECB. This 
routine also performs various post-I/O 
functions, such as adjusting magnetic tape 
block counts* In addition, the error retry 
routines are incorporated into the SPER 
routine. The CHECK macro instruction, 
issued by the user at soine point after his 
READ or WRITE, will test the indicators set 
by SPER. 

It the DECB indicated unit exception, 

the Check routine invokes Mainline* EOV # 
which in turn uses Tape Input EOV, Tape 
Output EOV, DA Input EOV # or DA Output EOV 
to complete EOV processing for tape or DA 
devices. Wh€3n end of volume is in fact an 
end of data set condition, processing will 
involve setting an end of data set indica- 
tion in the DCB. At this point Check is 
used to set up linkage to the user's end of 
data set routines if specified. 

For DA output devices at EOV but not end 
of data set, the Extend routine is called 
to try to get nwre space on the current 
volume. If and when another DA output 
volume is necessary, Bump is called to 
mount /dismount the next volume and, in 
t urn , E xt. end 1 s ns ed a ga i n t o ob t a in s pa ce 
on that volume. 

The Concatenation routine is used to 
link concatenated data sets. 

EOV processing is transparent to the 
user; when end of volume but not end of 
data set occurs on input, outstanding reads 
will be automatically reissued by the Check 
routine upon return from EOV. 

The end of data set indicator is reco- 
gnized in the Check routine, and linkage is 
made to the user's end of data set routine, 
if specified. 

In addition to Check, several other con- 
trol routines are available and used in 
BSAM: Note* Point , Backspace f Control, and 

Force End of Volume. 

To close his files, the user employs the 
CLOSE macro instruction which will link: to 
Close Common. This routine resets fields 
in the DCB filled in by the access methods. 
For nonshared data sets, it does the neces- 
sary recataloging for volume extents. 

Close Common will link to SAM Close. 
EOV is called to complete closing output 
tape or DA data sets. The Tape Output EOV 
routine will in turn utilize the label 
handling routines after it waits for out- 
standing I/O to quiesce. The SAM Close 



routine will release unused storage unless 
the user directs otherwise. 

Another basic BSAM module is the Message 
Writer, which is called by the Open, Close 
and EOV routiner, to handle most messages 

and console communication, and do most 
ABEND processing. 

See Section 6 of this PLM for routines 
specifically designed for BSAM. 

§ h^LS. SIE 1 ™!! 4 cat 1Qn §i2£iS : T ^ e ^ AM c o mrmm i ~ 

cation block is a table area used heavily 
by SAM Open, Close and EOV routines for 
pa s s i nq pa r ame t e rs. See Syst e m Control 
B loc ks PLM tor a detailed description of 
t^his table. 



MS AM OVERV IEW 

Data Sets, Buffers, a nd Blockin g Fact ors 

The Multiple Sequential Access Method 
CMSAM) provides a fast and efficient 
mechanism for simultaneously driving sever- 
al card readers, card punches, and printers 
under the control of a single user's task. 
Several data sets may be grouped together 
on any one device, allowing the user to 
process all of them under the same Data 
Control Block without opening and closing 
the DCB each time a data set with different 
characteristics is to be processed. Each 
of the separate data sets is referred to as 
a data group). Input data groups may be 
separated by control cards which consist of 
invalid EBCDIC characters in the first four 
columns and as many valid EBCDIC characters 
as required for control purposes. MS AM 
will recognize these control cards and 
notify the user that a control card has 
been read, allow inq him to take whatever 
action is necessary. Output data q roups ~>n 
the card punch may be separated with spe- 
cial cards from the reader by specifying 
the COMBIN option in the DCB macro instruc- 
tion, or they nay be removed from the read- 
er by the operator , who may be instructed 
to do so when a FINISH macro instruction is 
issued. 

MS AM differs from other sequential 
access methods in that each MSAM I/O requ- 
est of the system processes a buffer group 
of logical records, while each request 
issued by the other sequential access 
methods processes only a single physical 
record. Physical records are buffered by 
pages of virtual storaqe. MSAM processes a 
number of buffer pages based on an 
installation-provided parameter which is 
set in the symbolic device allocation table 
(SDAT) , and which may vary for each device. 
Its value may be adjusted to provide opti- 
mum device utilization when the number of 
records which can be contained on N pages 
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will drive the device full speed for the 
maximum length of time between the two con- 
secutive time slices. 

The first 32 bytes of each buffer page 
are reserved for control information used 
by MSAM. The remaining portion of the page 
is packed with format-F or format~V logical 
records. Format-F logical records are 
packed in the buffer starting with the 33rd 
byte in the buffer. Format-V logical reco- 
rds are packed in the buffer starting with 
the 37th byte in the buffer, since four 
bytes must be reserved as control bytes 
CLLBB) , as is the case with blocked, 
variable- length records. 

The number of records per buffer page is 
restricted to a maximum of 100 on input and 
200 on output. Depending on the size of 
the records, there may be fewer. 

The size of an input buffer will be com- 
puted by adding to the 3 2 control bytes the 
smaller product of (a) 100 times the logic- 
al record length, or Cb) multiplying by the 
logical record length the integral part of 
the result of dividing 4064 by the logical 
record length. 

The size of an output buffer will be 
regulated by the following rules. 

1. For fixed- length records, the number 
of bytes used for data will be the 
lower of (a) 200 times the logical 
record length, or Cb) the product of 
multiplying by the logical record 
length the integral part of the result 
of dividing 4064 by the logical record 
length. 

2. For variable-length records, the last 
record will have been placed in the 
buffer when (a) the record count 
reaches 2 00, or Cb) the sum of the 
user-provided control bytes CLL) of 
each record in the buffer plus the 
next expected logical record length 
plus four is greater than 4064. 

3- The buffer will be ended when form 

type-F is mounted on a printer, and a 
FORTRAN 3 - control character is found 
indicating a skip to channel 1. 

Schematic Description 

The user's problem program initializes 
for an MSAM I/O operation by defining a 
data control block with the DCB macro 



instruction, which generates a common por- 
tion and an MSAM portion of the DCB. The 
user then issues an OPEN macro instruction 
which links to the Open Common routine. 



Open Common completes the 
of the DCB from the TDT JFCB 
invokes MSAM Open to build a 
vide N buffer pages (where N 
in the SDAT set at system ge 
MSAM Open also provides N ha 
lORCBs and a DBP page, which 
work area by MSAM Read/Write 
DEB work page is also obtain 
save area for DOMSAM and to 
DECBs* MSAM Open formats N 
DECBs, and it checks the SDA 
for agreement and for valid 



common portion 
and then 

DEB and pro- 
is a constant 
neration time) * 
If-pages for 
is used as a 
and DOMSAM. A 
ed to use as a 
hold the N+l 
lORCBs and N 
T and tne DCB 
options . 



^Control characters defined by American 
National Standard FORTRAN, ANSI X3.9 - 
1966, hereinafter referred to as FORTRAN 
control characters (previously known as 
ASA or USASI control characters) . 



To set up online output devices, the 

user may issue a SETUR macro instruction. 
In the case of a print file, the SETUR rou- 
tine may read the two system VIP data sets, 

SYSURS and SYSUCS, to obtain the parameters 
necessary for setting up the printer. 
SETUR will issue WTO macro instructions and 
possibly IOCAL SVCs to the I/O supervisor 
to achieve the desired setup of the device. 

The user issues a GET macro instruction 
to obtain each card read from the card 
reader. Each GET macro instruction invokes 
the DOMSAM routine via type-1 linkage. If 
there are any records already in the buff- 
er, DOMSAM passes the next sequential reco- 
rd to the user. If the buffer is empty,, or 
if all the records in the buffer have 
already been processed, DOMSAM invokes MSAM 
Read/Write. 

The user issues a PUT macro instruction 
to print each line on the on-line printer 
or punch each card on the on-line punch- 
Each PUT will cause a record to be placed 
in a succeeding location of a buffer page. 
DOMSAM keeps account of these records to 
determine when the last record has been 
placed in the buffer. At that time, it 
invokes MSAM Read/Write. 

The MSAM Read/Write routine builds an 
IORCB and invokes the I/O Supervisor (IOS) 
via an IOCAL SVC. Each IORCB contains a 
list of CCWs for each record to be read or 
written. Each record read has a read CCW 
and a distinct feed, stacker select CCW 
associated with it. Each record written 
has essentially one CCW associated with it, 
for example, a punch, feed, select stacker 
CCW, or a print and space CCW. Additional 
control CCWs may be generated by MSAM at 
the beginning of the CCW list, such as skip 
to channel 1 on the printer. The lORCBs 
specify command and IORCB chaining and pro- 
vide the address of the MSAM Posting 
routine. 
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When the CCWs in an IORCB complete their 
execution, the currently running task pro- 
gram is interrupted, and MSAM Posting is 

given control from task monitor so that the 
necessary information may be stored in the 
DEB and in the DECB to inform DOMSAF of the 

I/O progress* If an I/O error has 
occurred, Posting will attempt the error 
re ":ry procedures. 

If intervention is required by the 
operator, Posting will record, in the DEB 

page f information about the IORCB returned 
by IOS in the ISA, and specify to the task 
monitor an asynchronous interruption rou- 
tine to be given control when the device is 
transferred from the not-ready state to the 
ready state. A WTO macro instruction is 
issued indicating the required action, and 
control is returned to the task monitor, 
which returns control to the routine which 
was interrupted for the posting operation. 
The asynchronous routine is part of the 
MS AM Posting routine, but it has a separate 
entry point. When given control , it will 
reissue, from the point of failure, the 
CCWs in the IORCB which was posted by MSAM 
Posting. 

By testing the return code from his GET 
or PUT macro instruction, the user can 
determine whether or not his operation has 
been completed. Before reissuing his 
incomplete GET or PUT, he is free to do 
other processing. Prior to reissuing a GET 
which returned an incomplete, the user 
should test the DECB pointed to by DCBCDE 
for completion; prior to reissuing a PUT 
which provides an incomplete return the 
user should test the DECB pointed to by 
DCBTDE for completion. If these DECBs are 
not complete and no further processing can 
be performed, the user may execute the 
AWAIT SVC in the DECB pointed to by DCBCDE 
or DCBTDE. 

When the processing for the current data 
group is completed, the user may issue the 
FINISH macro instruction, which will invoke 
the MS AM Finish routine. On output, this 
routine will initiate type-1 linkage to 
DOMSAM, which may in turn invoke MSAM Read/ 
Write for writing the last buffer on an 
output data group, and it will test the 
results of the write. It will wait for 
completion of all outstanding I/O requests 
for an input data group. Then it will 
notify the operator to remove the input or 
output data group from the device by a WTO f 
unless the user has indicated that such 
messages are to be suppressed. 

If the operator has been requested to 
respond to the message by readying the 
device, the Finish routine notifies the 
task monitor to recognize an interruption 
when the affected device is changed from 
the not-ready to ready state. This inter- 



ruption will give control to the Finish 
routine at its second entry point. The 
next time the Finish macro instruction is 
issued after this interruption is received, 
a return code other than incomplete is 
returned by the Finish routine to the user. 

When no more data groups are to be pro- 
cessed by the task on the device at the 

present time, the CLOSE macro instruction 
is issued. The Close Common routine is 
invoked and clears all fields of the DC3 
completed by Open Common . It then invokes 
MSAM Close, which issues a FINISH macro 
instruction, waits for completion, and 
releases the storage areas obtained by MSAM 
Open. 

MSAM Glossary 

Tables t* , 5 # 6, and 7 contain fields 
and/or flags used by MSAM which are fre- 
quently mentioned in the sections of this 
publication devoted to MSAM. 



RTAM OVERVIEW 

Activation of a terminal will cause an 
asynchronous interruption to be generated. 
The interruption will be fielded by the I/O 
Interruption Stacker routine in the resi- 
dent supervisor and placed on the channel 
Interruption processor queue. The Channel 
Interruption Processor determines that this 
is a terminal I/O interruption and passes 
it to the Terminal Communications Subpro- 
cessor, which is also resident. 

This terminal control is all taking 
place in the resident supervisor, as the 
RTAM abbreviation suggests. For details or 
an overview of the RTAM access method , s«-- 
tl *e Resident Supervisor PLM f GY28-2012 or 
the System Logic Summary PLM f GC28-2009. 

The Terminal Task Control routine, wb .*.■:. 
describes internals for some of the MTT 
user commands and macros, is described in 
this PLM. 



TAW OVERVIEW 

Privileged programs are the only ones 
that may issue READ/WRITE macro instruc- 
tions to directly call TAM Read/Write. 
Nonprivileged programs may only use the 
GATE I/O macro instructions that call an 
intermediate system's GATE routine that in 
turn calls TAM routines. The command sys- 
tem also invokes those GATE routines that 
link to TAM. All programs that use TAM 
routines either by a direct call or by th° 
intermediate system's GATE routine are 
restricted in that they may only be used 
with specific communication terminals. 
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Table ** . DCB Table Fields and Flags (MSAM 
Section) 



Table 



Some DECB Table Fields (CHADEC) 



1 Field 

V 



Flag | 



Meaning 



I rVRINHMS 

DCBCO^BI 
DCBICE 
DCBLKMAX 
DCBLRC 

DCBEAP 

DCBPPT 
LCBRCX 
DCBCNT 
DCBCDE 
DCBFDE 
DCBLDE 
DCBTDE 

DCBUDE 

DCBFRMTP 

DCBSTRIK 

DCBMSF1 

(MSAM 
flags) 



(M3AJ* 
flags) 



DCBEOP! 
DCBIOC 

DCBEOT 
DCBOVF 

dcbelp 

DCBNLP 

DCBPUR 
DCBSUR 

DCBFIN 
DCBFIP 

DCBFT 



Inhibit message to operator to remove 
data group 

Combine a reader on same 25U0 as punch 

Address of ICB named in SIR CO = none) 

Maximum allowable logical record length 

Address of current logical record in 
buffer for input records, or next 
available buffer location for output 
records 

Address of end of current buffer 

Address of current buffer page 

Internal return code 

Logical record count 

Address of current DECB 

Address of first DECB in list 

Address of last DECB in list 

Address of DECB to be tested for 
completion on a PUT 

Address of user's copy of erring DECB 

SYSURS form type for printing 

UCS strike out code 

End-of-buf f er processing needed 

Read/Write already invoked 

.buffer priming to be performed 

Format F new print page 

Last PUT issued was in locate mode 

Previous locate mode PUT being 
processed 

Purge all I/O at CLOSE 

SETUR in process 

FINISH just issued 
FINISH in progress 
First GET or PUT on a data group 



Table 5. Some DBP Table Fields 

Meaning 



r . „. — T . 

1 Field | 

l_„ +_ . „-— _- 

DBPPRTRY 1 Printer retry counter 

1 
DBPPRDC j Printer data check counter 

1 
DRPFRMTP | SYSURS form type code 

I 
DEPFOLD 1 SYSURS UCS folding code 

I 
DBPSTRK2 1 SYSURS UCS strike out code 

L -j. - — -» 



Field 


_ T T ^ 

\ Flag | Meaning | 

_-L_ „ X _ j 


DECECB 


IT — ' — ---f 

|DECEC0| Read/Write request • 


( oomplet ion 

code) 


| {code j 




JDECLCl j Normal Completion | 




|DECEC2| Complete with error | 




|DECEC3| Intercepted | 




IDECECU |Wait | 


DECLEN 


| |Data area length j 


DECCSW 


| | Channel status word | 

-X J™„ . . „ J 



Table 7. Some DEB Table Fields 



Fields 1 Flag 



Meaning 



I DEB IOC | | Number of outstanding! 

[ lORCBs 

I 
IDEBNF | DEBNF1 | Unrecoverable I/O 

| error 

I 
| DEBNF2 | Permanent I/O error 

I ! 
[DEBCLS | | Storage protection 

| class of DCB 

L. .__. . _X-»»„_ L . . — — 



During execution the OPEN macro instruc- 
tion provides linkage to the Open Common 
routine. Open Common locates the corres- 
ponding JFCB for the data set. Open Common 
links to TAM Open to continue special open 
functions, and then TAM Open returns to 
Open Common which sets bits in the DCB and 
the JFCB to say that the DCB is open. A 
counter in the JFCB is updated to indicate 
the number of DCBs that are open. 

During TAM Open f one page of storage is 
allocated and pointers are set up between 
this page and other control blocks. Part 
of this page is reserved for the DEB, which 
is partially completed during TAM Open with 
terminal information that was stored in the 
th€? symbolic device allocation table 
(SDAT) . The remainder of this page is 
reserved for the terminal operational sta- 
tus table (TOS) which includes the IORCB. 
The TOS is used as a work area during TAM 
Read/Write in order to complete the IORCB. 
Since the SDAT contains current information 
about the terminals, TAM Open increments 
the SDAT DCB open count for this terminal 
by one . 
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To accomplish a read/write function, the 
corresponding TAM GATRD/GATWR Macro 
instruction is required in the nonprivi- 
leged program while READ/WRITE macro 

instructions may be used in a privileged 
program. During assembly this generates a 

DECB that will be used to store the I/O 
status of this operation. During execution 
from the terminal information (terminal 

type and model code stored in the DEB dur- 
ing TAM Open) , and from the type option 
(stored in the DECB) , TAM Read/Write begins 
a table search. This search is through 
three internal tables (unit type, terminal 
library, and terminal control program) to 
locate a prestored channel program genera- 
tor CCPG) for the terminal* This CPG is 
made up of channel command word generators 
(CCWGs) that use the work area in the TOS 
to build channel comsand words CCCWs) and 
then move them into the IORCB. The I/O 
buffer area is also completed in the IORCB. 
The CCW list is executed by issuing an 
IOCAL SVC. This passes the IORCB to the 
I/O supervisor to execute the CCWs* At the 
completion of the I/O operation an inter- 
ruption occurs- The IORCB and the complete 
I/O status information are stored in the 
interruption storage area (ISA located at a 
fixed location of segment # page 0). 

TAM Posting processes this I/O interrup- 
tion by decoding the interruption data. 
The CCW list that was executed during TAM 
Read/Write is traced through again to loc- 
ate read CCWs . The Data In processor 
assures that the user read area is avail- 
able and translates and moves the data to 
this area. TAM Posting does not issue an 
ABEND upon noting exception or error condi- 
tions, but only posts this exception infor- 
mation in the DECB. It is the user's 
responsibility to verify correct operations 
with a CHECK macro instruction so the 
user's program may continue. However, if 
error conditions occur, the user's SYNAD 
routine may be entered where the address of 
t nis routine is pointed to by the DCB. 

When the user's I/O operations with the 
terminal are completed and a close is 
issued f the CLOSE macro instruction links 
to the Close Common routine. Close Common 
closes the DCB by restoring it to the ori- 
ginal status* Close Conuwon then links to 
TAM Close to continue the special close 
functions and then TAM Close returns to 
Close Common to reset bits in the DCB and 
• he JFCB to indicate a closed DCB. 

TAM Close frees the storage page allo- 
cated during TAM Open and resets the 

required pointers. 

The SDAT DCB open count for this termin- 
al is decremented by 1, For LOGOFF at all 
terminals, the disable/enable logoff func- 
tion imbedded in CLOSE is also required, A 



recursive call flag prevents a recursive 

loop between TAM Close and ABEND. 



IQREy i-VKKVlEW 

Privileged programs are the only ones 
that may use the IOREQ routines for unit 
record equipment or usinq SDAT. The IOREQ 
proqrams access data from any private I/O 

device. The data is accessed at the chan- 
nel command word level. A data set organi- 
zation of RX C IOREQ facility being used) 
must be specified in the DDEF command. 

When OPEN is issued f the Open Common 
routine openi; the DCB and locates th^ 
corresponding JFCB for the data set. Open 
Common links to IOR Open to continue spe- 
cial open functions and then IOR Open 
returns to Open Common which sets bits in 
the DCB and the JFCB to indicate the DCB is 
open . 



During this IOR OPEN, tests 
verify that; CI) the user's pr 
class is E for unit record equi 
IOREQ is specified in the DDEF 
IOREQ is allowed on the device, 
this device is a private volume 
is allocated for the DEB and th 
trol blocks with data type code 
moved from the JFCB to the DEB. 
check assures that the user is 
if access to the volume is priv 



are made to 
iviiege 
pment, (2) 

command, (3) 
and (4> 

Storage 
e IORCB con- 
information 
A final 
privileged, 
ileged. 



To accomplish a read/write, the IOREQ 
macro instruction is required in the user's 
program. This generates, during assembly f 

a DECB table that will be used to store the 
I/O status of this operation. The I/O 
operation is specified by VCCW utacro 
instructions specified in the user's pro- 
gram. These VCCW macro instructions are 
used by IOREQ to generate a list of CCWs to 
control the i/o activity. IOREQ places 
this list of CCWs in the IORCE. If buffer 
ing is requested by the user, space is 
allocated in the IORCB for the buffer dird, 
If buffering is not requested by the user, 
space xs allocated in the IORCB for page 
list entries to connect the CCWs to the I/O 
areas. The CCWs are executed by issuing an 
IOCAL SVC. This passes the IORCB to the 
I/O supervisor CIOS) to execute the CCWs. 
At the completion of the IOREQ I/O opera- 
tion an interruption occurs, and the IORCB 
and the complete I/O status information are 
stored in the interruption storaae area 
(ISA, located at a fixed location of seg- 
ment , page 0) . 

IOREQ Posting processes this I/O inter- 
ruption by analyzing the interruption data 
with all other task interruptions masked 
off. It then posts the normal or abnormal 
completion code in the DECB allowing the 
Check routine to later take action based on 
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these codes. IOREQ Posting does not con- 
tain any error recovery routines- The 
CHECK macro instruction must be used to 
ensure the completion of the I/O operation 
and to detect errors or exception condi- 
tions. If the I/O operation is successful t 
the program resumes execution at the 
instruction after the CHECK macro instruc- 
tion. If the I/O operation results in an 
unusual condition, the check of the DECB 
associated with this IOREQ causes control 
to be given to the user's SYNAD routine 
specified in his DCB. If multiple lOREQs 
are issued before a check of the first 
IOREQ is made, and one of these lOREQs 
generates an error, the subsequent lOREQs 
will be intercepted by IOS. It is the 
user's responsibility to reissue any IOREQ 
following the error-causing IOREQ. 



The CHECK macro instructions must, also 
be issued in the same order in which the 
associated IOREQ macro instructions were 
issued. 



When the user's I/O operations with the 
device are completed, the CLOSE macro 
instruction links to the Close Common rou- 
tine. Close Common then links to IOR Close 
to continue the special close function, and 
then IOR Close returns to Close Common to 
reset bits in the DCB and the JFCB to ind- 
icate a closed DCB. 

This IOR Close waits until all outstand- 
ing DECBs have been completed and then 
frees the storage allocated during IOR 

Open. 
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SECTION 2: 



OPEN PROCESSING 



COMMON PROCESSING 

The following routine is common to all 

access methods OPEN processing. 



Open Common Ro utine (CZCLA) 

The Open Common routine, called by the 

OPEN macro instruction, performs tho.se open 
functions^ common to ail access methods: 

• it checks for D€B error conditions, and 
ABEND:., if any exist. 

• It uses the GETMAIN macro instruction 
to acquiie a one-page work area, and 
passes the address of the work area as 
part of a parameter list when it links 
to the access-dependent Open routines. 

• It places the open options in the DCB 
for reference by the access-dependent 

open rout i nes . 

• If necessary, it issues a call to 
FINDJFCB to find tne JFCB associated 
with the data definition naine Cddname) 
of the DCB. 

• It i i 1 1 r i n cpi t .» in def au 1 1 , .j DCB 

1 1 elds w , t h inf o r ir.« t i o n f r e m t h e corre- 
sponding tieidiv \n the JFCT. . it keeps 
track of the DCB 1'ieids so modified, so 
that at CLOSE time the DCB can be 
restored to it: ft— OPEN status. 

In addition to these operations common 
lo all dci'e?:, methods, Open Common automat- 
ically catalogs all VAM data sets. 

O p e n i : o mmo n links ^ o t h e a p o r c pi i a t e 

routine for access- dependent opvn pieces- 
s i n g f C ha r t AA ) . 

A;, cri out e i ; : Reontr a n t , r e s i d e n t i n v i r t ua 1 

s'->«jage, closed, read-only, privileg€*d rou- 
tine, public. 

Entry Poin t: CZCLAu - ■• Hnt fivd oy c/pe-1 
or type -2 linkage. 

iDPHt : Reqister 1 contains the riddrrst; of 

H-- CHAGSM table. CHAGSM (the general ser- 

••• c*i, macro table) r built by the expansion 
wi i. h*- OPEN macro instruction, consists of 
one doubleword entry for each DCB to be 

opened. 

Data References : CHADCB, CHATOT, CHAGSM, 
CHAISA. 



SAM Open CCZCWO) — SAM Open. 
TAM Open (CZCYA> — TAJM Open. 
MSAM Open (CZCMC) — MSAM Open. 

Open VAM CCZCOA) -- VAM Open. 

10R Open fCZCSC) -- IOR Open. 

vm CCZCGA) — Get virtual storage, 

Addcat ICZCFA) — Catalogs all VAM data 
sets* 

Search SD5T CCZCQE) — Search shared data 
set table* 



Index sequential 



Modules Called : 
FINDJFCB CCZAEB) 



Find JFCB. 



Read/Write CCZCPE) 
read/write* 

Exits ; 

Normal -- Return to calling program. 

Error -- ABEND macro instruction. 

Operation : Open Common provides DCB 
addressability and checks for valid DCB 
identifier and nonzero ddname. If an error 
condition exists f the task will ABEND. 

One of the primary functions of Open is 
to find the JFCB for the data set being 
opened. If the data set is concatenated, 
the address of the JFCB is picked up from 
DCBCON; otberwise f the routine examines the 
TDT for the JFCB address. If still not 
found, the address of the JFCB is obtained 
through a call to the FINDJFCB routine. 

Following the call to FINDJFCB, VAM data 
sets are automatically cataloged by calling 

Addcat . 

A user with read-only access is allowed 
to open a VAM data set even though he has 
specified it as modifiable for his purposes 
COOTPUT, EDIT, or other options). This 
allows him to use the data set locking fea- 
ture; he will be prevented from modifying 
the data set by the VAM output routines. 
An existing read-only data set not of VAM 
organization and specified by the user with 
other than the INPUT option will result in 
an ABEND. 

Open Common will turn on the conca- 
tenated system flag in the DCB if the J^CB 

describes a concatenated data set. 

The zero DCB fields are filled in with 
corresponding entries from the JFCB f enabl- 
ing the user to specify many data set 
characteristics and handling options for 
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this run that were not specified during 
assembly. 

Open Common gets a page of storage which 
is used by the BSAM for IORCBs, and by 
fence stxaddlers and VAM for save areas, 
tnen links to tne appropriate access- 
dependent open routines. 

Upon return from the access dependent 
routine , Open Common tests for other DCBs 
to be opened. The entire procedure is 
repeated for each DCB and when all DCBs 
have been opened, control is returned to 
the calling routine. 



User Prompter (CZATJ1) -- Write a warning 
message. 

VMA (CZCGA2, CZCHA2) — Get virtual 
storage. 

VMA CCZCHA3) -- Free virtual storage. 

Volume Sequence Convert (CZCWV1) -- Volume 
address conversion. 



E xits : 

Normal -- Return to calling program. 

Error -- Issue ABEND. 



SAM OPEN PROCESSING 

The following routines are common to SAM 

processing . 

SAM Open Mainline Routine (CZCWO) 

This routine performs opening functions 
common to sequential access methods. It 
branches to the Open Tape or Open DA rou- 
tines to have the open processing completed 
for magnetic tape or direct access devices 
respectively (Chart AB> • 

Attributes ; Reentrant, resident in virtual 
storage, closed, privileged. 

Entry Point : CZCWOl — Entered only by 
type~l linkage. 

Input : When this routine is entered, 
register 1 contains the address of the fol- 
lowing three word parameter list: 

Word 1 — Address of DCB being opened. 

Word 2 — Address of associated JFCB. 

Word 3 — Address of work area for building 

IORCBS. 

The PSECT of CZCWO contains the SAM com- 
munication block CCHASCB) , three temporary 
control blocks - a DCB f a DEB and a DECB 
which are used by the label processors for 
reading or writing tape labels, and a para- 
meter area for reading and writing format- 1 
DSCBS. 

Data References : CHADCB, CHADEB, CHASCB, 
CHATDT, CHADEC. 

Modules Called : 

DA Open (CZCWDl) — Open direct access. 



Tape Open (CZCWT1) 



Open tape. 



Mainline EOV (CZCXE1) — Write EOV trailer 
and header labels when BOV encountered 
during header label processing. 



Operation : The SAM Open Mainline routine 
initializes the SAM communication block 
(CHASCB). If a DCB is currently opened on 
the JFCB, the task is abnormally ter- 
minated. Open options are checked against 
the JFCB disposition parameter to see if a 
data set with a disposition of NEW is 
opened for input. If it is, and the task 
is nonconversational, the task is abnormal- 
ly terminated; for conversational mode 
tasks, the routine gives the user a warning 
and the option to continue. 

SAM Open checks to make sure that the 
data set has a mounted volume, and that the 
proper volume is mounted. The routine also 
checks to make sure no reading will be per- 
formed on output data sets, or writing on 
input data sets. 

The main function performed by SAM Open 
is the building of the data extent block in 
privileged storage so that it cannot be 
destroyed or changed by the user program. 

If the device assigned to the data set 
is a magnetic tape or direct access device, 
control is given to Tape Open or DA Open 
respectively. These routines, in turn, 
call the proper DEB building routine. 

If Tape Open or DA Open had been given 
control, any storage dynamically obtained 
by either routine is released by calling 
FREEMAIN, and normal return is made to the 
user. 

Whenever Tape Open or DA Open encounters 
errors, it posts an abnormal condition code 
in the SCB and terminates via ABEND. 

In case an end-of -volume condition 
occurs while Tape Open is writing the head- 
er, SAM Mainline will call Mainline EOV to 
end the present tape with an EOV trailer 
label and write the header on a new tape. 

The block size of ASCII format tapes is 
checked for minimum (18 bytes) and maximum 
(2048 bytes) length. 
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QOPEN is bypassed if neither GET nor PUT 
is indicated in the macro field of the DCB. 

If the data set being opened i3 a QSAM data 

set, then QOPEN, a section of SAM Open 
Mainline, is entered to perform those func- 
tions unique to a QSAM data set. If 

blocked records were indicated in the DCB 

and the biocksize is zero, an ABEOT) exit is 
taken. Otherwise, the block size is set 
equal to the maximum logical record length* 
Then, the number of buffers to be obtained 
for the data set roust be determined. If 
the data set is opened for UPDATE, and 
CNTRL is specified in the DCB f only one 
buffer is needed. If the data set is 
opened for RDBACK, and if the record format 
is variable* three buffers must be 
obtained* Otherwise, two buffers must be 
obtained. The storage for buffers is 
obtained by issuing a GETMA1N macro 
instruction which returns the address of 
the area obtained in register 1. This 
address is saved in the DCB. If two or 
three buffers are needed, their addresses 
are calculated and stored in the DCB, The 
protection class of the area will be the 
same as that of the DCB. For data sets 
using only one buffer, the DCB field indi- 
cating the maximum number of reads or 
writes which may be done before a check is 
set to one, and for all others it is set to 
two. Then the same procedure described 
above is followed to obtain storage for 
QSAM's qwk work area* CSee the QSAM sec- 
tion of this publication for a description 
of the QWK work area.) 

The V-cons for the entry points CZCSAA, 
CZCSAB, CZCSAX, and CZCSAS are set into the 
DCB. If the data set is opened for output, 
the GET V-con field in the DCB CDCBGTV) is 
set to one. Otherwise, the POT V-con field 
CDCBPTV) is set to one. This is to insure 
that no GETs are issued on an output data 
set, and no PUTs issued on an input data 
set. 

Tape Open Routine (CZCwT) 

The Tape Open routine completes the open 
processing for a sequentially organized 
data set on magnetic tape. It builds a 
data extent block (DEB), uses the appropri- 
ate label processor to process tape labels, 
and completes the tape recording informa- 
tion fields in the DCB. CSee Chart AC.) 



labels, as well as pointers to the actual 
DCB being opened and its associated JFCB. 

8M a Hef <frence«: chadcb, chatdt, chascr, 

CHADEn", CHAIOA. 

Modules Called : 

Control CCZCRB) — Magnetic tape 
positioning. 

Bump CCZCAB) ~ Request and verify mount of 
new volume, 

VMA (CZCGA) -- Get virtual storage. 

LVPRV CCZCJL) — Leave privileged state. 

Build Common DEB CCZCWB) -- Build the com- 
mon portion of a DEB, 

Tape Data Set Label CCZCWY) — Tape label 
processor. 

Tape Positioning CCZCWP) — Position tape. 

User Prompter CCZCTJ) -- Inform user of 
error. 

Exits : 

Normal -- Return to calling program. 

Error — Via ABEND macro instruction. 

Operation : If the tape is labeled, GETMAIN 
is called to get an area of virtual storage 
for label buffers. If the routine deter- 
mines from the SCB that the correct volume 
for the data set is not mounted, the Bump 
routine is called to mount the proper 
volume. 

The Build Common DEB routine is called 
to build the common portion of the DEB for 
the data set being opened. This portion of 
the DEB is copied into the "temporary" DEB 
pointed to by the SAM communication block 
for use in processing labels. 

The tape volume is positioned by calling 
the Tape Positioning routine; the volume 
labels are then written or read via Tape 
Data Set Label- If the OPEN option is 
INPUT, INOUT, or RDBACK f or if the JFCB 
indicates MOD* the data set labels are pro- 
cessed as input; otherwise the label is 
processed as output. 



Attr ibutes : Reentrant, resident in virtual 
storage, closed, read-only, privileged. 



Entry Points ; 
1 linkage. 



CZCWT1 



Entered with type- 



Input: Register 1 contains the address of 
the SAM communication block CCHASCB) . Note 
that the SCB contains pointers to a DCB, 
DEB, and a DECB in the SAM Open PSECT which 
are used for reading or writing tape 



The labels are processed unless the JFCB 
indicates no labels. If the user requests 
it, he is given control at this time, 
through the DCB exit, to modify the DCB. 

The tape recording fields in the user's 
DCB are completed. The User Prompter rou- 
tine is called to request directions from 
the user if there are incompatibilities in 
the user's specifications for tape record- 
ing in his DCB| for example, recording 
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density of 200 bits per inch is incompat- 
ible with 9-track magnetic tape. Should 
the user not supply a satisfactory solution 
to the problem. Tape Open will effect an 
abnormal end with an ABEND. 

DA Open Routine (CZCWD) 

The DA Open (Direct Access Open) routine 
completes the open processing for a SAM 

data set on a direct access device. It 
builds a data extent block CDEB) , process ■■ , 
DSCBs and user labels, sets necessary 
fields in the DEB, and makes sure the prop- 
er data set volume is mounted. (See Chart 
AD.) 

Attributes : Reentrant, resides in virtual 
storage, closed, read-only, privileged- 

Entry Point : CZCWD1 -- Entered by type-! 
linkage. 

Input ; Register 1 contains the address of 
the SAM communication block (CHASCB) . 

Data References : CHATDT, CHADSC, CHADCB, 
CHADEB, CHASDA, CHASCB, CHAISA. 

Modules Called ; 

Bump CCZCAB) — Request and verify mounting 

of new volume* 

Obtain/retain CCZCPO) — Obtain DA user 
label and retain DA user label. 

VMA CCZCGA) - Get virtual storage. 

LVPRV CCZCJL) — Leave privileged state. 

Build DA DEB (CZCWL) -- Build direct access 
DEB. 

User Prompter CCZCTJ) — Inform user of 
error. 

Read Format- 3 DSCBs (CZCWR) — Read and 
chain format- 3 DSCBs. 

DA Input Label CCZCXN) — Direct access 
input label processor. 

DA Output Label (CZCXU) — Direct access 
output label processor. 

Exit s; 

Normal — Return to the calling routine. 

Error — Via ABEND. 

Operation ; If the volume to be processed 
is not the one which is mounted, DA Open 
calls the Bump routine to mount the proper 
volume. 

The Obtain routine is called to get the 
format-1 DSCB for the data set. If the 
integrity bit is on in the DSCB, a PRMPT 



macro is issued to ask the user if he wants 
to continue. The integrity bit is set on 
when the data set is opened, and set off at 
EOV or CLOSE by Set DSCB. Therefore, if 
the integrity bit is already on during the 
open process, the data set was previously 
opened but never closed. 

If the data is being opened for output 
and has a disposition of OLD, and the 
expiration date in the DSCB has not been 
reached, a PRMPT macro is issued to ask the 
user if he wants to write on the unexpired 
data set. The Retain routine is used to 
write the format-1 DSCB on the volume. For 
old data sets, zero DCB fields are com- 
pleted with fields from the format-1 DSCB, 
and the expiration date is stored in the 
JFCB from the DSCB field. 

Should the data set have format-3 DSCBs, 
they are read by calling the Read Format- 3 
DSCB routine. Then since all extents are 
known, the Build DA DEB routine is called 
to build a direct access DEB. 

If the user labels are specified, GET- 
MAIN is used to get buffer space for label 
processing. 

DA Open sets on the integrity bit in the 
format-1 DSCB when processing a volume with 
a data set opened for OUTPUT, OUTIN, or 
INOUT. As processing of each volume is 
completed, the integrity bit is reset by 
other BSAM routines. 

The DEB is set to point to the first 
data record except for a data set with dis- 
position MOD. In the latter case, the DEB 
is set to point to the end of the last data 
record as indicated in the format-1 DSCB. 

The user labels are then read or written 
using either the DA Input User Label pro- 
cessor or the DA Output User Label 
Processor. 



DEB PROCESSING 

The following routines are used to build 
or modify the data extent blocks* 



Build Common DEB Routine CCZCWB) 

The Build Common DEB routine may be 
entered to perform either of two functions. 
It can obtain virtual storage to create a 
DEB and initialize the DEB's common por- 
tion. Alternatively, Build Common DEB may 
be called to modify the common portion of 
an existing DEB. (See Chart AE. ) 

Attributes ; Reentrant, resident in virtual 
storage, closed, privileged. 
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Entry Point : 
linkage. 



CZCWB1 — Entered by type-1 



Input : Register 1 contains the address of 
the SAM communication block CCHASCB) . 

Data References : CHASCB, CHADCB, CHADEB, 
CHATDT, CHASDA. 

Modules Called : 

VMA CCZCGA) — Get virtual storage. 

User Prompter (CZCTJ) — Issue message to 
user. 

Exits : 

NGrmal -- Return to calling routine. 

Error ~ Via ABEND. 

Operation : When the routine is called to 
build the common portions of the DEB f 
storage is obtained via GETMAIN and' all the 
fields in the common portions of the CHADEB 

which can be filled from the CHADCB, CHAS- 
DA, and CHASCB are initialized. The 
remaining fields of the CHADEB are zeros. 

If the routine is called to reinitialize 
fields for the appropriate CHASDA, Build 
Common DEB reinitializes, in both the CHA- 
DEB and the temporary access method CHADEB, 
those fields originally obtained from the 
CHASDA and DEVOL. 

This routine abnormally terminates if 
the size of the CHADEB equals zero. 

Build DA DEB Routine (CZCWL) 

The Build DA DEB routine creates a data 
extent block (DEB) for the first volume of 
a data set on a direct access device. 
Additionally, it can add extents to an 
existing DEB, or build a new DEB for a mul- 
tivoiume data set when the extents indi- 
cated in the old DEB are obsolete. (See 
Chart AF.l 

Attributes : Reentrant, resident in virtual 
storage, closed, privileged. 



Entry Point : 
linkage. 

,;.i put : Regi 
,:ne SAM coram 
^HASCB will 

rent DEB, a 
and/or forma 
whether the 
extend a DA 
the chained 



CZCWL1 



Entered by type~l 



ter 1 contains the address of 
unication block CCHASCB). The 
contain a pointer to the cur- 
pointer to a chain or format- 1 
t-3 DSCBs, and an indication of 
routine is to construct or 
DEB. The routine assumes that 
DSCBs are in virtual storage. 



Modules Called : 

VMA (CZCGA) — Get virtual storage, free 
virtual storage. 

Point CCZCRM) -- Logically reposition data 
set. 

Build Common DEB (CZCWB) -- Build and modi- 
fy the common portion of the DEB. 

User Prompter (CZCTJ) -- Issue message to 
user. 



Exits : 
Normal 



Return to caller , 



Data References : CHASCB, CHADEB, CHADSC f 
CHADCB, CHATDT, CHASDA. 



Error ~ Via ABEND. 

Operation : This routine first calculates 
the actual size (in bytes) of the DEB. The 
size is the sum of: the number of bytes in 
the conmon portion of the DEB, four times 
the number of channel programs (DCBNCP) 
less one, the number of bytes in the fixed 
length direct access portion of the DEB f 
and sixteen times the number of extents to 
be contained in the DEB. The number of 
extents is determined by searching the 
DSCBs until either a null extent type code 
or a null CCHHR chain address is found. 

If the data set has not been opened f the 
Build Common DEB routine is called to con- 
struct and initialize the common portion of 
a DEB. The extents Caddresses) are then 
stored in the DEB from the indication of 
extents in the DSCB chain. Control is then 
returned to the calling routine. 

If the data set is open, this routine 
has been entered with a DEB already in 
existence. Therefore, a new DEB must be 
generated and the present extents entered 
in it. 

GETMAIN is called to obtain virtual 
storage for the new DEB. If the next 
extent to be processed is zero, the fixed 
portion of the old DEB is moved into the 
new DEB, and the Build Common DEB routine 
is called to modify the volume and device 
fields in the DEB. Should the next extent 
to be processed be non-zero, the common and 
fixed direct access portions of the old DEB 
are copied into the new DEB, and Build Com- 
mon DEB is called for the volume and device 
field modifications of the new DEB. The 
DEB fields for next I/O, last I/O, and last 
write addresses are initialized. If the 
JFCB indicates DISP=MOD # Point is called to 
position logically to the end of the data 
set. In either case FREEMAIN is called to 
release the storage of the old DEB, and 
extents are added to the new DEB on the 
basis of those extents currently indicated 
in the DSCB chain. Control is returned to 
the calling routine. 
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This routine abnormally terminates if: 

1- The DSCB extents are not equal to the 
number of calculated extents. 

2. The DSCB extents are not numbered in 
consecutive order. 



D >CB PROCESSING 

The following routines concern SAM DSCB 
processing . 

Read Format-3 DSCBs Routine CCZCWR) 

The Read Format -3 DSCBs routine causes 
all format- 3 DSCBs associated with one 
volume of a data set to be read into virtu- 
al storage and chained together. (See 
Chart AG. ) 

Attributes ; Reentrant, resident in virtual 
storage, privileged. 

Entry Point : CZCWR1 — Entered by type-1 
linkage. 

Input : Register 1 contains the address of 
the SAM communication block (CHASCB) . 

Data References ; CHASCB, CHADSC, CHADEB. 

Modules Called ; 

Obtain/Retain CCZCFO) ~ Obtain DA user 
label. 

VMA (CZCGA) — Get virtual storage. 

User Prompter (CZCTJ) — Issue message to 
user. 

Exits ; 

Normal — Return to the calling routine 

Error — Via ABEND. 

Operation ; It is necessary to compute the 
amount of virtual storage needed for read- 
ing the forma t-3 DSCBs. The correct number 
of bytes is calculated and stored in 
SCBF3Z. GETMAIN is called to get that cal- 
culated number of bytes of virtual storage. 

The DSCBs are then read into the storage 
which GETMAIN supplied. The Obtain routine 
is used to read each DSCB. The DSCBs are 
chained together. Where there are no more 
DSCBs to be read, control is returned to 
the calling routine. 

Set DSCB Routine (CZCXS) 



The Set DSCB routine updates the infor- 
mation in format- 1 DSCBs, turns off the 
integrity bit in the format-1 DSCB, and 
writes a file mark on the DA output volume. 
(See Chart AH.) 



Attributes ; Reentrant, resident in virtual 
storage, closed, read-only, privileged. 



Entry Point ; CZCXS1 ~- Entered by type-1 
linkage. 

Input : Register 1 contains the address of 
the SAM conmunication block (CHASCB) . 

Data References ; CHADEB, CHADCB, CHADSC , 
CHASCB, CHASDA, CHATDT, CHADEC. 

Modules Called : 

Read/Write (CZCRA) — BSAM read/write. 

Obtain/Retain fCZCFO) -- Obtain DA user 
label and retain DA user label, 

FULREL (CZCRS) — Convert full DA address 
to relative address. 

User Prompter CCZCTJ) -- Communicate with 
user. 

Exits : 

Normal — Return to calling program. 

Error — Via ABEND. 

Operation ; If the SCBRF1 flag is on, the 
format-1 DSCB is read, the integrity bit is 

set off, and the DSCB is written. 

Otherwise, the format-1 DSCB is read via 
OBTAIN, and the DCB type fields in the 
format-1 DSCB, volume sequence number, and 
the last volume bit are written. The Last 
Record pointer is set to point to the last 
record written, the bytes left on the track 
are stored in DSCLRD, the integrity bit is 
set off, and the format-1 DSCB is rewritten 
via RETAIN to reflect the above. A file 
mark is placed following the last record 
that was written on the volume and the 
SCBFLG, which contains the SCBRF1 flag, is 
set to zero. 



MSAM PROCESSING 

The following routines are used with 
MSAM processing. 



MSAM Open Routine CCZCMC ) 

The MSAM Open routine edits the DCB and 
SDAT for valid options and combinations of 
options, and constructs control tables 
(DEB, lORCBs, and DECBs) and work areas 
(DEB page and buffer pages) in virtual 
storage for use by the multiple sequential 
access method. (See Chart AI. ) 

Attributes ; Reentrant, read-only, public, 
privileged, system, nonrecursive. 
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Entry Point : CZCMC1 -- Entered by type-1 
linkage from Open Common when the DSORG 

field of the DCB specifies MS. 

Input : When this routine is entered, 
register 1 contains the address of the fol- 
lowing parameter lists 

Word 1 — Address of the DCB. 

Word 2 — Address of the TDT JFCB. 

Data References : CHADCB, CM AS DA # CHATDT f 

CHADEB, CHAD EC, CHAIOR § CHAICB, CBADBP. 

Modules Called ; 

VMA (CZCGA) — Get virtual storage* 

CKCLS CCEAQH) — Check storage protection 
class. 
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Exits : 

itormal -- Return to Open Common. 

Error -- Via ABEND. 

Operatio n: When MSAM Open is entered, 
register 1 contains the address of a para- 
meter list which contains a full word 
pointing to the DCB and a full word point- 
ing to the TDT JFCB. MSAM Open accesses 
these two addresses, and obtains the 
address of the SDAT from the TDT. If a DCB 
has bc^en opened previously for this data 
set, the task is abnormally terminated 
unless it is a remote job entry CEJE) task. 
If it is RJE f the task is abnormally ter- 
minated if more than one previous DCB has 
been opened. CThe JFCB indicates a pre- 
viously opened DCB.) 

There are two tables CTBDD1B and TBDD2B) 
in MS .AM Open for each of the device depen- 
dent, parameter fields in the DCB. These 
tables contain the allowable parameters and 
the default parameters for the particular 
device dependent fields. If the value of a 
device dependent field does not match any 
of the allowable parameters, the default 
parameter is stored in the field. Checks 
are made on fields of the DCB and SDAT for 
valid options and combinations of options* 
Any invalid condition causes abnormal ter- 
mination of the task with the appropriate 
message displayed on SYSOUT via the ABEND 
macro instruction. 

The value of N, the maximum number of 
allowable IORCBs, is obtained from the SDAT 
and a check is made to determine the 
storage protection class of the DCB. If 
the DCB is Class A (user read-write) f a 
GETMAIN macro instruction is issued to 
obtain (N*3)/2 contiguous pages of Class B 
(user read-only) virtual storage. These 
pages will be used for the DEB page and the 
(N+D/2 IORCB pages which cannot be of 
Class A storage, (See Figure 2 and Figure 
3.) A pointer to the first page obtained 
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is stored in the DCB. A second GETMAIN is 
then issued to obtain N+l contiguous pages 
of Class A virtual storage for the DEB work 
page and the N buffer pages which must be 
of the same protection class as the DCB. 

if the DCB is Class B (user read-only) 
or Class C {user inaccessible) , a single 
GETMAIN is issued for <3N*5)/2 contiguous 

pages of virtual storage of the same pro- 
tection class as the DCB« In both cases the 
same number of pages are obtained^ although 
in the first case the two groups of pages 
will not necessarily be contiguous* Except 
for the case where the DEB and IORCB pages 
cannot be Class A, all pages obtained are 
of the same class as the DCB. 

Fields in the DEB may now be initia- 
lized, and pointers set to the other con- 
trol tables. For an RJE task, DEB pointers 
in the TDT JFCB are enchained if a previous 
DEB has been created during the task. A 
skeleton ICB is built to specify an 
attention-type interruption* with pointers 
to the DCB and associated coxraminication 
area. The fixed area of an IORCB is built, 
and additional fields in the DEB page are 
initialized for use by the other MSAM 
modules. If RJE, flags are set in the 
IORCB and the DEB. 

Next, N skeleton DECBs are built in the 
DEB work page following the 19 word save 

area of DOMSAM, and a pointer to the first 

DECS is set into the DCB. To initialize 
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for looping, the DCB pointer to the current 
DECB is initialized to the address of the 
first DECB. 

For fixed record format, the number of 
logical records in the buffer is then com- 
puted as the buffer size divided by the 
logical record length, where the buffer 
size is equal to 4096 minus the number of 
control bytes (currently 32). If this 
count of logical records is greater than 
100 on input, it is set to 100, and if i 
is greater than 200 on output, it is set to 
200. For variable record format, th . nui. L-- 
er of logical records in the buffer is 
initialized at zero. If RJE, logical reco- 
rd size is stored in the DEB work page 
area. The following fields are calculated 
and saved: the maximum record count for 
RJE PUT t40«*8/(LRECL*2*lS))/2*2; the maxi- 
mum record count for the RJE first PUT of 
the first IORCB with machine control chara- 
cters <4040/(LRECL+2 + 15))/2*2 f - and the 
maximum size of the PUT logical record 
CLRECL*l*15)/8*8. After calculation of 
logical record size and count limit, a loop 
is performed to initialize N skeleton 
DECBs. 

Now the N XORCBs are initialized in 
their half pages. The fixed area of the 
first IORCB (at the beginning of the first 
full page beyond the DEB page) is built. 
Since each of the other N-l lORCBs is to be 
built in the same manner as the first, the 
fixed area of the first IORCB is moved to 
these other N-l XORCBs, which are located 
at successive half-page boundaries follow- 
ing the first IORCB. 

Next, the fields in the MS AM portion of 
the DCB are initialized. The DCB pointers 
to the last, the current, and the user's 
DECBs are set, and the fields indicating 
the number of logical records and the 
return code are both set to zero. A flag 
is set in the DCB to indicate that the next 
GET or PUT issued will be the first on this 
data group. 

The DCB macro field is then tested. If 
it specifies PUT, the DOMSAM PUT VCON and 
RCON are set into their respective fields 
in the DCB, and unused VCONs in the DCB are 
set to full words of hexadecimal Fs. If 
the records are fixed length, the address 
of the current logical record is computed 
as the beginning-of-buff er address plus the 
number of control bytes. If the records 
are variable length, a test is made for an 
RJE task. If RJE, the address of the cur- 
rent logical record is set to the 
beginning -of- buffer address plus the number 
of control bytes plus 9. If not RJE, it is 
set to the beginning-of-buf f er address plus 
the number of control bytes plus 4, and the 
block control bytes (LLBB) are initialized 
to X'OOO^C'bb' . 



If the 'DCB macro field specifies GET, 
the DOMSAM GET VCON and RCON are t;et iiito 
their respective fields in the Dcii,. and 
unused VCONs are set to fuLl words of hexa- 
decimal Fs . 

Control is then returned to Open Common. 
There is no return code- 



SETUR Routine (CZCMD) 

The Set: Unit Record (SETUR) routine spe- 
cifies the unit record configuration for a 
local or remote printer or a card punch. 
It is called as the result of a user- 
initiated SETUR macro instruction, indicat- 
ing how a device is to be set up tor a job. 
If the device is not already correctly set. 
up, the SETUR routine requests an operator 
to set the device as specified by the macro 
and sends the user return codes indicating 
the results. (See Chart AJ.) 



At tributes : Privileged, reentrants read- 
only, public, system, nonrecursive. 

Entry Points : 

CZCMD1 -- Primary entry point entered with 
type-1 or type- 2 linkage. 

CZCMD2 ~ Asynchronous entry point entered 
with type- 2 linkage. 

CZCMD3 — Synchronous entry point entered 
with type-1 linkage. 

Input : 

For entry at CZCMD1 , register contains 
the address of the unit record device 
setup parameter and register 1 contains 
the DCB address. 

For entry at CZCMD 2, register 1 contains 

the ICB address. 

For entry at CZCMD3, the ISA contains the 
IORCB. 

Data Refer ences : CHADCB, CHASDA, CHADEB, 
CHAIOR, CHAICB, CEAI5A, CHADBP. 

Modules Cal led: 

WTO (CZABQ) — Write message to operator ov 
console typewriter. 

SIR (CZCJS) — Specify interruption 
routine. 

DIR (CZCJD) — Delete interruption routine. 

Open (CZCLA) -- Open a data control block- 
Find (CZCOJ) -- Find a member of a VPAM 
data set. 

Read CCZCPE) — Read a V1SAM record. 
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Close CCZCLB) — Close a data control 
block. 

Reset (CEAAH) — • Reenable a device after 

I/O error- 
Exits s 



Normal — For return from CZCMD1 register 
15 contains one of the following codes: 



• 00 1 

•08' 

» 0C , 

f 10 s 



Completed successfully • 

Incomplete, 

Unrecoverable I/O error. 

Bad parameter for SYSUR5 key. 

Invalid SYSUCS key specified 
by SYSURS. 

Intervention required on RJE 
device. 



For return from CZCMD2 or CZCMD3 regist- 
er 15 contains f 00 f . 

Error -- Abnonial termination via the ABEND 
macro instruction. 

Operat ion; The operation at the three 
entry points is: 

MAIN ENTR Y AT CZCMDlz SETUR abnormally 
terminates it the DEB or DCB is invalid, or 
if the DCB has not been opened. 

Since the SETOR macro instruction is 
issued repetively by the user until he 
receives a return code other than 4 (incom- 
plete) # the SETUR routine must determine 
conditions existing each time it is 
invoked. The internal return code in 
DCBBCX, in combination with the SETUR-in- 
progress switch CDCBSUR) , determines the 
line of processing to be followed upon 
entry- DCBSUR is set on when SETOR is 
first called for a device; it is set off 
when SETOR has completed its processing , or 
when the invoking routine wishes to notify 
SETUR to stop its processing when it is 
next given control* Processing for the 
various DCBSUR, DCBRCX combinations is as 
follows : 

DCBS U R o ft, DC BRCX less than 100 : If the 
device is other than a card punch or a 
printer (or, if an RJE task, other than a 
, rir.rer), SETUR exits to the caller with a 
return code of normal completion. 

For a ca t 3 punch : CDCBSUR off, DCBRCX 
less than 100). If the setup parameter 
card form number is the same as the SDAT 
form number, normal ending procedures are 
followed. The return code is set for norm- 
al completion, DCBSUR is set off, and con- 
trol returns to the calling routine. 



If the numbers are not equal, a message 
is sent to the operator via WTO requesting 
him to mount the desired form, CZCMD2 is 
specified as the asynchronous entry point 
and SETUR returns to the caller with a 
return code for incomplete while operator 
response is awaited. 

For a printer (or f if RJE # remote print- 
er) : CDCBSUR off, DCBRCX less than 100). 
If the setup parameter key is the same as 
the SDAT URS key, the desired configuration 

is already set, so normal ending procedures 
are followed as with the card punch. 

Otherwise, the DCB for the VPAM data set 
containing the member $SYSURS is opened, 
and the four-line SYSURS record is read 
according to the key given in the setup 
parameter. If an error occurs on a READ # 
SETUR saves the error information in the 
MSAM DCB, closes the SYSURS file, turns 
DCBSUR off, and exits to the caller with a 
return code indicating either "invalid SYS- 
URS key* or * unrecoverable error*. When 
the SYSURS record has been read successful- 
ly f the SYSURS DCB is closed and checks are 
made for appropriate printing specifica- 
tions and valid SYSURS parameters, SETUR 
abnormally terminates if the conditions 
checked for are not met. 

SETUR now checks that the required print 
form, carriage tape* print chain/train and 
density are now being used. If any of these 
need to be changed f an appropriate message 
is sent to the operator via the WTO macro 
instruction, or, if an RJE task, to the re- 
mote operator via an IOCAL macro instruc- 
tion, after building a special IORCB. 
CZCMD2 is specified as the asynchronous en- 
try point by a SIR macro instruction unless 
the task is RJE, in which case this entry 
point will have been specified as part of 
BULRIO initialization, SETUR returns an 
•incomplete 1 indication while local or re- 
mote operator response is awaited. 

If no such changes are necessary, the 
SYSURS form type value is saved in the DCB, 
and SETUR tests for use of the Universal 
Character Set CUCS) feature* 

For UCS printing , SETUR abnormally ter- 
minates if the folding code is invalid. If 
the SDAT and SYSURS values for the UCS key 
do not match* the DCB for the VPAM data set 
containing the VIP member $SYSUCS is 
opened, and the 5- line SYSUCS record is 
READ according to the key given in SYSURS. 
If no error occurred on the read opera- 
tions, the SYSUCS DCB is closed, an IORCB 
is built to load the UCS buffer and Is 
executed with CZCMD3 specified as its post- 
ing entry point. SETUR then exits to the 
caller with a return code for incomplete* 
If an error occurred when reading the SYS- 
UCS record, the SYSUCS file is closed. 
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DCBSUR is set off, and SETUR returns to the 
caller with a return code for an invalid 
SYSUC3 key or data set. VAM error return 
inf onciation may be found in the MSAM DCB. 

If the SDAT and SYSURS valuer, for the 
UCS k^y match, the UC3 buffer doer, not have 
to be loaded. If the UCS strikeout. 
character is to be used, it is tested for 
validity (ABEND results if it is invalid) 
and converted and saved in the DCB. The 
SYSURS folding code is saved in the SDAT, 
and SETUR proceeds to test for printer ali- 
gnment (see below). 

If the UCS feature is not in use, loading 
the UCS buffer is not necessary,, so testing 
for print alignment occurs immediately. 

If print alignment is necessary (unless 
an RJE task) , an IORCB specifying CZCMD3 as 
its posting entry point is built to print 
50 lines on the printer for purposes of 
alignment. A message? is sent to the opera- 
tor via WTO requesting him to align the 
printer, and SETUR returns an incomplete 
while operator response is awaited. CZCMD2 
is specified as the asynchronous entry 
point. 

If no alignment is necessary, or i f the 
task is RJE (in which case alignment is not 
possible) , processing is completed. The 
URS key from the setup parameter is stored 
in SDAT, DCBSUR is set off, any active 
interruption is deleted, (not necessary if 
the task is RJE) , and control returns to 
the caller with the return code in register 
15 set to "completed successfully" or "com- 
pieted with unrecoverable I/O error." 

DCBSUR on, DCBRCX not in the range 100 
through 136 ; SETUR abnormally terminates 

when this invalid condition occurs. 

DCBSUR on, DCBRCX = 100: The operator has 
not yet mounted the requested form on the 
card punch. Until he docs, control is 
returned to the caller with a return code 
for incomplete. 

DCBSUR on, DCBRCX = 10*1 s The operator has 
mounted the specified form on the card 
punch as requested. The punch form number 
from the setup parameter is therefore moved 

into the corresponding field in the SDAT, 
and normal ending procedures (see above) 
are followed. 

DCBSUR on, DCBRCX = 108 : The operator has 
not yet mounted or set the SYSURS- specified 
form, carriage tape, chain/train or density 
on the printer as requested. Control 
returns to the user with a return code for 
incomplete. 

DCBSUR on, DCBRCX = 112 ; The operator has 
mounted or set the requested form, carriage 



tape, chain/train, and density for the 
printer. The corresponding four SDAT 
fields are therefore set from the SYSURS- 
specified values, and processing continues 
as if tne four SDAT fields were already 
correctly set (see above). 
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DCBSUR on, DCBRCX = 120 : SETUR is in the 
process of printing the UCS buffer and 
verification message. If the printing is 
not yet complete, control returns to the 
caller with a return code for incomplete. 
If the printing is complete, but the DEB 
indicates an error, DCBSUR is turned off 
and SETUR exits to the caller with a mes- 
sage to the operator and return codes for 
"unrecoverable- error*. If intervention is 
required , the message is sent to the opera- 
tor with return code indicating incomplete. 
If there is no error, a WTO is issued to 
write the EBCDIC form of the verification 
message on the operator's console, and to 
request that the operator verify that this 
verification message matches the one pre- 
viously printed on the printer. C2CMD2 is 
specified as the asynchronous entry point, 
and SETUR returns to the caller with a 
return code for incomplete while operator 
response is awaited. 

DCBSUR on, DCBRCX = 124 ; The operator has 
r- t yet verified that the print line 

• peared identical on the printer and the 
jsole. Control is returned to the caller 
*,xt.h a return code for incomplete. 

D CBSUR on, DCBRCX = 128 ; The operator has 
verified the UCS printing. The UCS key is 
stored in the SDAT and the universal- 
character- set bit is turned on in the DCB. 
Processing then continues as if the SDAT 
and SYSURS values for the UCS key matched 
(see above) . 

DCBSUR on. DCBRCX = 132 s The alignment 
lines are being printed and the operator is 
checking printer alignment. If the DEB 
indicates an error, any active interruption 
is deleted; DCBSUR is turned off, and con- 
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ti'ol returns t o the caller with a message 

to f r i c • operator and return code for "unre- 
coverable error". It no error is indi- 
cated, control returns to the caller with a 
i't turn code for incomplete. 



control returns to the task monitor with a 
return code of in .register 15. 



DChSUR on. DCBRCX 



136: 



The operator has 
nccessfully aligned his print form. If a 
rint IOHCB is still outstanding, control 
s returned to the caller with a return 
••ue for incomplete. If there is no out- 
tnkiing 10RCB, processing continues; as if 
o alignment were necessary (see above) . 



DC BSUR on, DCBRCX = 140 : A start I/O error 
retry has failed and DCBRCX is set to 140 
before returning from the SETUR synchronous 
interruption routine entered at CZCMD3. At 

t ne next SETUR macro instruction the SETUR 
routine, entered at its main entry point, 
will detect this condition, set a return 
code of 8 (unrecoverable I/O error)' in 
register 15, and return. 

DCBSUR off, DCBRCX not less than 100 ; Th e 
caller has turned' off the DCB SETUR~in~ 

progress bit in order to prematurely ter- 
minate the SETUR processing. In this case, 
the SDAT carriage tape, chain/train* fold- 
ing option, UCS key f URS key, and density 
fields are zeroed if the device is a 
printer. 

ASYNCHRONOUS INTERRUPT ENTRY AT C2CMD2 : 
SETUR is given control at its asynchronous 
entry point, CZCMD2, when an operator 
response fan attention interruption caused 
by changing the state of a device from "not 
ready* to "ready 18 ) is received. 



If neit 

m t erven ti 
DCBRCX is 

less there 
indicated, 
IOCAL SVC 
alignment 
kJE, the i 
deleted. 
the caller 
register 1 



her printer alignment nor 
on-required retry is in progress t 
incremented by 4. Otherwise, un- 
is an outstanding 10RCB or error 
a RESET will be issued and an 
executed . Then f unless printer 
is in progress or the task is 
nterruption routine will be 
In all cases, control returns to 
with a return code of in 



S YNCHRONOUS INTERRUPTION ENTRY AT CZCMD3 : 
The synchronous entry point of SETUR is 
given control by the task monitor when the 
I/O activity associated with an IORCB 
terminates . 

Errors occurring during the I/O activity 

*ul reB'ilt in either no retry or limited 

retry, depending upon the type of error. 

Any final error is recorded in the DEB- 

If a unit check or unit exception is 
indicated when alignment is in progress, 
out no intervention is required and no 
errors are indicated, DCBRCX is incremented 
by 4 to indicate completion of alignment, 
and the number of outstanding lORCBs is 
reduced to zero. Then, as in all cases, 
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The following routine is used with Ter- 
minal Access Method (TAM) processing. 

TAM Open Routine CCZCYA ) 

In continuing the open processing from 
Open Common 9 TAM Open is called to perform 
additional opening functions for terminals. 
This includes building control blocks and 
providing buffer areas for initiating com- 
munications with a terminal. TAM Open then 
returns to Open Common except when an 
abnormal end is required , in which case it 
goes to ABEND. (See Chart AK. ) 

Attributes : Reentrant, resident in virtual 
storage, closed, read-only, privileged. 

Entry Point : CZCYA1 — Entered by type-1 
linkage. 

Input : When this routine is entered, 
register 1 contains the address of the fol- 
lowing parameter list: 

Word 1 -- Address of the current DCB being 
opened. 

Word 2 -- Address of the associated JFCB. 

Data References ; CHADCB, CHATDT f CHASDA, 
OH A DEB, CHATOS. 

Modules Called : 

Write (CZCYM) -- TAM write. 

Check (CZCRC) « Check, 

VMA (CZCGA) — Get virtual storage. 

LVPRV CCZCJL) -- Leave privilege mode. 

WTO CCZABQ) — Write to operator. 

ABEND (CZACP) — Abnormal task termination. 

ADDEV CCEAAC) — ■ Add device to task device 
list, 

RMDEV (CEAAD) — Remove device from task 
device list. 



2 4 
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Exits : 

Normal — Normal RETURN to calling routine. 

Error -- ABEND macro instruction. 

Operation : TAM Open initially saves the 
general registers, gets the TOS page and 
examines the number of DCBs that were 
opened for a given terminal. 

• If this number is equal to 0, the ter- 
minal definition is checked. 

• If this number is greater than and 
less than or equal to 255, TAM Open 
continues the processing by updating 
the count of DCBs in the SDAT. 

• If this number is greater than 255 (the 
maximum number of opened DCBs allowed 
for a terminal) , TAM Open branches to 
ABEND. 

The terminal is checked for definition 
and type when the first DCB is opened for 
this terminal. 

• if the terminal is defined, TAM Open 
continues the processing by updating 
the count of DCBs in the SDAT. 

• if the terminal is not defined this 
routine branches to ABEND. 

• If the terminal is defined and is eith- 
er a 2741 or a 1050, the system must 
determine which of the two terminal 
types is involved. This determination 
is made by issuing the LCD macro 
instruction. 

TAM Open issues a GETMAIN . macro instruc- 
tion to obtain one page of virtual storage 
for the data extent block (DEB) , and the 
terminal operational status table (TOS) 
which includes the I/O request control 
block CIORCB) . Pointers are set up between 
these blocks and blocks that were created 
before* TAM Open, and are illustrated in 
Figure 4. The purpose of these pointers 
between TAM Open allocated blocks and pre- 
viously existing blocks is to facilitate 
their use by all TAM routines under normal 
and abnormal conditions. 

DEB virtual storage, after being ini- 
tially allocated during TAM Open, has the 
following pointers set and data moved: 

(A) The DEB is pointed to by the DCB. 

CB) The DEB points to the DCB and the 
SDAT. 

CO The DEB points to the SDAT terminal 
information. This SDAT terminal 
information pointer is moved from the 
JFCB. 
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(a) Blocks created before TAM OPEN 

* Blocks for which TAM OPEN allocates space 

-► Pointers existing before TAM OPEN 

-► Pointers set up during TAM OPEN 



77777%. Data moved during TAM OPEN 
jWordl-^- Parameter list pointers 



Figure **. TAM Open: DEB and TOS Storage 
Allocation and Pointers 



CD) The SDAT terminal information is 

loaded into the DEI J. This teririnal 

information is loaded into the DEB. 
This terminal information is used by 
the TAM Read/Write and TAM routines 
and includes the terminal type, con- 
trol unit type r data adapter and model 
code of the terminal. 

TOS virtual storage is allocated by TAM 
OPEN and is pointed to by the DCB. TAM 
Read/Write uses the TOS area to build the 
channel command words. It is also used by 
TAM Read/Write, TAM Posting, and TAM Open 
for communication of common information. 

Processing ends with the terminal DCB 
open count in SDAT incremented by 1 for 
this current DCB and a return to Open 
Common . 
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_ •_ '• PR OCESSING 

Tr " toi lowing routine is used with 
".;:■:•;•■. '"Output Request (IOR) processing, 

:>-!!. upci^ Ro utine (C ZCSC) 

In continuing the open processing f rom 
\. •■; "'GiYvmon, I OR Open is called to allocate 
■ i'cr-ige for control blocks and complete the 
• quiL'c'i fields in the DEB to allow the 
'.i;c«osing of the 10REQ macro instruction. 

IOR Open then returns to Open Common 
: -. op,- wni. n an abnormal end is required, in 
' ;, :h \ise it goes to ABEND. CSee Chart 



set organization requirements must be 
specified at data definition time only. 



• The user-supplied NCP parameter, in the 
DCB macro instruction, is not greater 
than the maximum CDCBNCP=99) • If the 

user did not set a value, or set a 

value of zero, a value of 1 is 
inserted- 



• The volume is not public* as indicated 
by the volume public flag (TDTV1=G) not 
being set. IOREQ can only be used on 
private volumes. 



hhlJLJjl^ ; " './ : reentrant, resident in virtual 

:-••- .£o.:p^ -"iosed, nonrecursive, read-only, 

''■.'•" : i.*;.....i;oiiiA : CZCSC1 -- Entered with type-1 

\: rjuf : : iv'ht j n this routine is entered, 
v>::ii.it^r 1 contains the address of the fol- 
- ■ :•.; j ,a r a met er list: 

...... -,j i ~~ Address of DCB being opened, 

: > '< tC ,. -- Address of associated JFCB. 

'•••; .' i \ - - Address of workpage obtained by 
O .- r; C< -mmon. 



Riitti'jnces: 



CHADCB, CBATOT, CHASDA, 



CHAO&O 

VHA CCACGA) -~ Get virtual storage. 
CKCLS (CEAQ4) -- Check protection class. 

„•. . r-.j- --- Return to calling routine. 

Error — ABEND macro instruction. 

:1/££.2±A2R ; IOR OPEN saves the general 
■ :r-'.TT. stars . Tests are then made ' to check 



c The lUREw facility is allowed on the 
device, by checking that the SDAIOR 
field in SDAT is equal to one. 

* The DCB identification is valid, by 
checking that the DCBID identifier is 
equal to *%*%. 

• The TDT indicates that the IOREQ faci- 
lity is specified in the DD command 
CTDTDSV=RX). The DCB was previously 
checked in Open Common (DCBDSO=RX) 

which called for IOR Open, The data 



An ABEND exit is taken if any of the 
above error conditions occur. Processing 
continues by caluclating the area needed 
for the DEB plus additional contiguous 
bytes for the IORCB. The length of the DEB 
is set to contain a common area plus extra 
storage for each NCP specified. This 
amount is rounded to a multiple of eight so 
that the contiguous bytes to build the 
IORCB originate on a doubleword boundary. 

IOR Open then requests, with a GETMAIN 
macro instruction, one page of virtual 
storage for DEB and IORCB to be used by 
IOREQ and IOREQ Posting. This area is ini~ 
tially 2eroed« 

DEB virtual storage, after being ini- 
tially allocated during IOR Open # has the 
following pointers set and data moved 
Crefer to Figure 5>: 

CA) The DEB is pointed to by the DCB and 
JFCB. 

CB) The DEB points to the DCB and JFCB. 
CO The DEB points to the IORCB . 

CD) The DEB points to the SDAT address 
and device address information. 
These SDAT information pointers are 
contained in the JFCB, 

CE) The JFCB data type code information 
is moved to the DEB. 

Some other DEB fields listed below are 
also completed; 

• The identification field CDEBID) is set 
to *(. 

• The size field CDEBSIZ) is set to DEB 
area size. 

• The IOREQ Posting VC0N CDEBPSV) is set 
to IOREQ Posting entry point and the 
RCON CDEBPSR) is set to IOREQ Posting 
PSECT address. 
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DEB pointers, to and from DCB and JFCB, and to IORCB 



►. SDAT pointers from JFCB moved to DEB 

'Z//r////7?Z / Data Type Code information moved from JFCB to DEB 

Figure 5. IOR OPEN: Basic Pointers and Data Moved from JFCB to DEB 



• The number of channel programs (NCP) 
field in DEB (DEBNP) is set to the 
value in the DCB field- (DCBNP) . 

• The DEBDVC field is set with a hex code 
indicating the device (magnetic tape, 
direct access, unit record) . 

• The DEBUNT field is set with a hex code 
indicating the unit type C2400, 2311, 

• The maximum number of iORCBs allowed 
field in the DEB (DEBIO) is set to the 
maximum in the SDAT field CSDAMRB) . 

• The DCB protection class field in the 
DEB (DEBCLS) is set to the appropriate 
value. It is as obtained as a result 
of an SV"C f generated by a CKCLS macro 
instruction. A final check on this 
value within IOR Open assures that the 
user is privileged if the access to the 
volume is privileged- 



A pointer to the DECB field in the DEB 
CDEBDEL) is not completed during IOR 
Open but during IOREQ. However, the 
address of DEBDEL is stored in a DCB 
field (DCBDEC) durinq IOR Open. 



A final check is made of both the DCB 
protection class and the type of access to 

the device. Then, 



If the DCB protection class is not pri- 
vileged C DEBCLS +1) and the type of 
access to the device is privileged 
(TDTVPY=1) r an ABEND exit occurs. 



• If no DCB protection class can be 
determined 9 an ABEND exit occurs. 



If neither of the above criteria are 
met, a return to Open Common occurs. 
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SECTION 3: READ/WRITE 



READ/WRI TE PROCESSING 

This section describes the BSAM Read and 
Write, MS AM Get, Put r Read and Write, TAM 

Read and Write, and IOREQ routines. 



The Read/Write routine creates an IORCB 

which contains the appropriate channel com- 
mands to perform the I/O operation which is 
requested by the BSAM READ or WRITE macro 
instruction. The IORCB is passed to the 
I/O supervisor so the channel coomands may 
be executed. CSee Chart BA. ) 

Attribute s; Reentrant, resident in virtual 
storage, closed, read-only, privileged* 
nonrecurs ive . 

Eft try Points ; 

CZCRAS -- Main entry point to the Read/ 
Write routine; entered by type-1 or 
type- 2 linkage. 

C2CRDS -- Entry point for building an IORCB 
(Build subroutine); entered by type-1 

linkage. 

CZCRES — Entry point for adding the chan- 
nel program (Construct subroutine); 
entered by type-1 linkage* 

Input : Register 1 contains the address of 
a DECB containing all information which was 
coded as parameters of a Read or Write 
instruction. 

Data References : CBASDA, CHAIOR, CHADCB, 
■.■'.'HADEB, CHADEC, CHAVPS. 

Modules Called : 

AWAIT (CEAP7) ~ Await an interruption. 

IOCAL CCEAAO) ~ I/O call. 

CKCLS (CEAQ4) ~ Check protection class, 

ASCII Translation and Conversion CCZCWA) — 
when an. ASCII Write request is 
encountered. 

Exits : 

Normal — Return to the calling routine. 

Error — Abnormal termination of task by 
ABEND macro instruction* 

Operation : The main entry point processing 
at CZCRAS is as follows: 



During open processinq, a queue cf 
zeroed DECB pointers is established in the 
DEB for the data set. The main routine 
stores the address of the input DECB point- 
ers in the reserved pointer area. 

When this routine is entered, if the 

passed DECB is the same as the first DECB 
in the queue, it is the Check routine that 
has entered the Main routine to have a read 
or write request reissued* 

if entry was not by Check, the new DECB 
is inserted into the queue if there is 
room. The ^in use" and •intercepted 88 flags 
are set on in the new DECB- Should the 
"number of lORCBs allowed" 8 count permit 
another IORCB to be given to the I/O super- 
visor* a search of the queue of DECBs is 
initiated to find the first request to be 
fulfilled. If that particular DECB is 
associated with an ASCII Write request that 
was intercepted by the I/O supervisor, a 
call to the ASCII Translation and Conver- 
sion routine (CZCWA) is made to put the 
record back in EBCDIC format. Then the 
main routine proceeds to have the IORCB 
built by the Build routine and filled in by 
the Construct routine* Successful con- 
struction of an IORCB will then permit the 
main routine to execute the IOCAL SVC which 
requests the I/O supervisor to perform the 
I/O operation. 

The build entry point processing at 
CZCRDS is as follows: The Build routine 
generates a skeleton IORCB and stores sev- 
eral parameters in it* 

Build returns to the Main routine which 
stores the address of the SAM Posting rou- 
tine in the IORCB* and branches to the Con- 
struct routine to complete the IORCB by 
constructing a channel program in it. 

The construct entry point processing at 
CZCRES is as follows: The Construct rou- 
tine is passed a pointer to the skeleton 
IORCB which was generated by Build . The 
Construct routine must complete the IORCB 
so that it may be used by IOCAL* Fami- 
liarity with IOCAL as presented in System 
Programmer's Guide s GC28-2O08 # is required 
to understand the logic of Construct; . 

The first decision Construct must make 
is whether to use the IORCB as a buffer or 
to build a page list which points to the 
user's data pages. If the data exceeds 
1800 bytes 9 the IORCB cannot be used as a 
buffer 9 and a page list must be 
constructed* 
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For 7-track tape the channel program 
which is generated consists of two CCWs. 
The first CCW is a Mode Set command which 
sets the density, data converter, and tran- 
slator as specified in the tape option 
field in the DCB. The second CCW is the 
read or write command. For 9-track tape, 
just the one CCW for the read or write is 
required. 

For an ASCII write request, ASCII Trans- 
lation and Conversion is called to transl- 
ate the data to be written from EBCDIC to 
ASCII and convert variable-length records 
from V to D format (standard IBM to Ameri- 
can National Standard) . ASCII output may 
occur only to 9-track tape. 

For direct access, the channel program 
is more complex. The generated channel 
program depends on whether the requested 
operation is a read or write, whether track 

overflow is specified, and what the record 
format is. 

The channel program for a DA read is 
generated as follows. A full DA device 
address is in the form bbCCHHR, where bb is 
two bytes which indicate bin number (data 
cell) , CC is two bytes which indicate 
cylinder number, HH is two bytes which ind- 
icate track (or head) number, and R is the 
record number on the track. The first CCWs 
are two Seek commands to the next I/O 
address (bbCCHH) which is found in the DEB. 
The first Seek command is software chained 
because a seek takes a relatively long time 
to execute (arm movement may be necessary) , 
and hardware chaining of commands makes the 
channel unavailable to other tasks. There- 
fore, software chaining will cause the two 
seeks to be executed without locking other 
users out of the channel. The second seek 
command is command chained to the rest of 
the CCWs in the channel program, so execu- 
tion of the second seek gives the task 
exclusive control of the channel until the 
execution of the channel program is con- 
cluded. The next CCW is a search for the 
identifier CCHHR, which will position the 
DA device to the key field of the record. 
A TIC command follows the search to cause 
the channel program to loop until the reco- 
rd is found. The Read command (read key 
and data) is next in the channel program 
and it is followed by a NOP command. 

When reading format-U or V records, it 
is not known where the next record to be 
read is. This is because the number of 
bytes in the current record is not known. 
If the end of the current record cannot be 
calculated, the beginning of the next reco- 
rd is not known. So when reading format-U 
records, the search command is directed to 
the last I/O address. Then three CCWs are 
generated: read-no transmit, read, and 
NOP. The R£AD~no transmit causes the last 



record to be passed by the reading head, 
and the read key and data causes the 
correct record to be read. 

The channel program for a DA write is 
generated as follows. Using the last write 
address from the DEB, the first four chan- 
nel commands are generated: seek, seek, 
search, TIC. The reason for using the last 
I/O address is that it is known where the 
last record was written, but if format-U 
records are being written, it is not known 
where the next record should go. Then a 
read-no transmit, followed by a write- 
count, key, data is generated. The Read-no 
transmit brings the head past the last 
record which was written and then the WRITE 
puts the new record on the volume sequen- 
tially following the previous record. If 
track overflow is specified and the record 
to be written is larger than the room 
remaining on the current track, the record 
is begun on the current track and continues 
on the next sequential track. However, no 
record can be split between cylinders on a 
DA volume. 

As in the channel proqram for a DA read, 
the write channel program is ended by a NOP. 

The Construct routine uses closed sub- 
routines to help in the completion of the 
IORCB. They are: 

ENTCCW — Enters a CCW into the IORCB. 

SCHCCW — Generates SEEK, SEARCH, and TI.C 

CCWs, and puts them in the IORCB. 

SETPAG — ■ Sets up a page list in the IORCB. 

NXTIO — Computes the MBBCCHHR of the next 
record to be written on a DA 
volume. 

Intercepting a Read or Write Request : The 
DECB which is passed to the SAM Read/Write 
routine contains an intercept flag set by 
SAM Read/Write when the I/O request is not 
actually initiated. ( IOCAL is not given 
the IORCB built for the DECB). 

There are several reasons why the I/O 
request of a particular DECB may not be 
initiated. For example, if a read request 
is given and the current volume was used up 
on the preceding read, the DECB is set as 
intercepted and the EOV request flag in the 
DECB is set on. If a write request is 
given and there is no more room in the cur- 
rently allocated extents, the same flags 
are set. If the DECBs request I/O on the 
same devices and the first one encounters a 
hardware error condition, the intercept 
flags in the remaining DECBs are set on so 
the I/O will not be initiated unless the 
hardware error is cleared up. If this were 
not done, each DECB I/O request could run 
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into the same hardware problem and a per- 
manent error would be found, not once, but 

many times. 

When a DECB is operated upon by the 

Check routine, the intercepted flag is 
tested. Should there be no serious error 
conditions posted in the DECB, the Check 
routine , in addition to performing other 
services, will reinitiate the I/O request 
by passing the DECB back to the Read/Write 
routine. This I/O request is given immedi- 
at e attention by Read/Write because it is 
the first entry in the queue, 

DOMSAM Routine CCZCME) 



f 10" Control card sensed reading. Regist- 
er 1 points to control card in buffer 
if locate mode, user area if wove 
mode. Register points to user DECB 

•1U* intervention is required in an RJE 

task because the line is discon- 
nected. (No record is obtained.) 

Normal -- Following a PUT , register 15 con- 
tains one of the following return codes; 

•00 1 Normal completion. Register 1 points 
to next available location in buffer 
if locate mode, to user area if move 
mode* 



DOMSAM blocks and deblocks logical reco- 
rds into system buffers when GETs or PUTs 
are issued, invokes MSAM READ/WRITE to 
build and execute the IORCB necessary for 
I/O, and provides the user with a return 
code describing the outcome of his GET or 
PUT request. The routine runs in the same 
privilege as its caller* ISee Chart BB. ) 

Attributes : Read-only, public, reentrant, 
nonrecursive, assumes privilege of caller* 

Entry Points; 

CZCME1 ~ Entered upon issuance of a GET 
macro instruction which generates type-1 

linkage. 

CZCME2 -~ Entered upon issuance of a PUT 
macro instruction which generates type-1 
linkage. 

Input : 

Register -- Address of user- specified 
area for move mode GET or PUT. 

Register 1 -- Address of the DCB* 

Data References ; CHADCB* CHADEB, CHADEC f 
CHADBP, CHAISA." 

ftodul es Called: MSAM Read/Write CCZCMF) -- 
To read or write records. 



i 04 i 



Request incomplete. 



s 08 f Unrecoverable I/O error. Register 1 
points to buffer of record that 
failed to be written* Register 
points to user DECB. 

• 0C Intervention is required in an RJE 
task because the line is discon- 
nected* CNo record is written) 

Error — - ABEND macro instruction is used 
for abnormal end termination* 

Operation : » DOMSAM has no PSECT. It uses 
the first 19 fullwords of the DEB work page 
as its standard register save area, obtains 
adcons from the DEB page (CHADBP) f and 
maintains switches and other variable 
information in the MSAM portion of the DCB, 
its work areas are the DEB work page, which 
contains DECBs, and the buffer pages. 

Upon entry to DOMSAM, a transfer pointer 
is set to indicate whether a GET or a PUT 
has been issued* Checks are then performed 
to be certain that the DCB and the DEB are 
valid, and that the DCB has been opened. If 
any one of the three conditions is not wet, 
execution is terminated by an ABEND macro 
instruction. If all conditions are met, 
processing is categorized as GET or PUT, 



Exits ; 

Normal -- Following a GET , register 15 con- 
tains one of the following return codes: 

'00 f Normal completion . Register 1 points 
to record obtained in buffer if loc- 
ate ntode # user area if move mode. 

*QU« Request incomplete . 

•08 f Unrecoverable I/O error. Register 1 
points to C failing) record in buffer 
if locate mode, in user area if move 
mode register points to user DECB, 

■0C f End of data set reading- (No record 
obtained). Register points to user 

DECB. 



GET Processing : If the GET macro instruc- 
tion is the first issued on the data group , 
or if the previous GET emptied a buffer, 
the end-of-buf f er switch in the DCB will to* 
on. In this case, MSAM Read/Write roust be 
invoked to either prime all the buffers or 
refill the buffer just processed. If prim- 
ing is to be done, no lORCBs may be out- 
standing or the return code will be set to 
indicate incomplete, and a return will be 
made to the caller . 

For each buffer to be filled, the cur- 
rent DECB is marked in use (read/write 
requested) and initialized* and MSAM Read/ 
Write is invoked. Upon return from Read/ 
Write, the current DECB is checked to see 
if it is the last in the list, and if so, 
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its pointer is reset to point to the first 
DECB. If not, the DECB pointer is incre- 
mented to point to the next DECB. 

A check is then made to see if all the 
buffers are to be primed, and if so, the 
next buffer is filled by setting up the 
DECB and invoking MSAM Read/Write as 
before, until the last DECB has been pro- 
cessed. At that point, the current DECB 
address is reset to point to the first 
DECB. 

The DCB pointer to the current buffer 
page is set to the address of the buffer 
associated with the current DECB. Then the 
DECB is tested for completion* and if the 
I/O is not yet complete, control is 
returned to the caller with a return code 
indicating that the GET has not been com- 
pleted and must be reissued at a later 
time. In an RJE task, if the line to the 
remote device is not connected, the return 
code will indicate intervention is 
required* 

If the DECB is posted complete and indi- 
cates normal completion with neither a unit 
check (indicating that a control card has 
been read) nor a unit exception (indicating 
end of data set) , the normal completion 
code of zero is set into the DCB for even- 
tual use as a return code. The pointer to 
the current logical record within the buff- 
er is then set immediately beyond the 32 
control bytes in the buffer, and the end- 
of -buffer address is computed by adding to 
that address the product of the logical 
record length and number of records that 
can fit in the buffer. Following a trans- 
mission from a remote reader (RJE task), 
this end~of~buffer address is adjusted 
based on whether an odd or even number of 
logical records were read into the buffer. 

If the DECB is posted complete without 
errors, but unit check or unit exception is 
indicated, or if the DECB is posted com- 
plete with errors, the appropriate return 
code is set into the DCB, and a copy of the 
current DECB is moved to the user's DECB 
area. In this case, the end-of-buf f er 
address is computed as the byte immediately 
following the last normal input record by 
adding the displacement-to-error field of 
the DECB's modified CSW to the beginning- 
of -buffer address. This displacement must 
be decremented by 84 if, in an RJE task, 
only one logical record was read in during 
the last transmission. The current logical 
record address is computed as 32 bytes 
beyond the beginning of the buffer. 

Following this, or if no buffer priming 
or refilling was necessary to begin with, a 
check is made to determine if the current 
logical record is valid by comparing the 
record address with the end-of -buf fer 



address. If it xs lower, normal steps will 
be taken to get the record for the user. 
Otherwise, one of the unusual conditions 
(end-of -data-set, control card, or record 

with error) exists, and the return code in 
the DCB is set into register 15 for the 
user. The end-of- buf fer and buffer-priming 
switches are set, the count of logical 

records within the buffer is set to zero, 
and the pointer tc the current DECB is 
reset to point to the first DECB in the 
list so thct the next GET issued will re- 
prime all the buffers. If the unusual con- 
dition is an end-of -data set, there is no 
record to be obtained for the user, and 
control is returned immediately. However, 
if there is a record beyond the buffer end 
address (either a control card or a record 
with an error) , it is returned to the user 
as described below. 

when the current logical record is 
valid, it must be returned to the user. If 
the GET is in locate mode, the current 
record address is set into register 1; if 
the GET is in move mode, the record is 
moved to the user-specified area whose 
address was supplied in register 0. The 
current record address is then incremented 
by the logical record length to point to 
the next record, and the count of logical 
records already processed within the buffer 
is incremented by one. If the record 
address is no longer less than the end-of - 
buffer address, or if the count of logical 
records is 100, the current buffer is com- 
pletely processed. In that case, the end- 
of- buffer switch in the DCB is set on to 
indicate that end-of -buf fer processing is 
necessary before the next GET can be com- 
pleted, and the count of logical records is 
reinitialized to zero. Whether or not this 
GET emptied a buffer, the return code is 
set to zero, signifying normal completion 
of the GET, and control is returned to the 
caller. 

If, upon entry to DOMSAM, the end-of - 

buffer switch is on, and if a FINISH macro 
instruction was previously issued, edits 
and initialization largely of the type per- 
formed by MSAM Open are required before 
MSAM Read/Write may be invoked to reprime 
all the buffers. If any permanent errors 
have occurred, or if any lORCBs remain out- 
standing, the task is abnormally ter- 
minated; if not, a flag is set in the DCB 
to indicate that this is the first GET 
issued on the data group, the buffer- 
priming switch is set on, and the FINISH- 
just-issued flag is turned off. 

The record format is checked to be cer- 
tain it is not variable. If variable, the 
task is abnormally terminated since vari- 
able format records are not supported for 
the card reader. If not variable, the 
maximum allowable record length is calcu- 
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lated, and compared with the value speci- 
fied by the user. If the user-specif ied 
value is not greater than zero and less 
than or equal to the computed maximum* the 
task is abnormally terminated. If the 
record length is acceptable, the count of 
logical records within the buffer :Ls set to 
zero, and the maximum number of logical 
records per buffer is computed and" stored 
in each DECB« The current DECB pointer is 
set to point to the first DECB in the list, 
the acknowledgement CACK) switch is initia- 
lized for RJE, and the routine proceeds 
with buffer priming as described above* 

PUT Processing ; Initially, for both local 
and RJE jobs , if the PUT before the current 
one was not in locate mode, and if no end- 
of-buffer processing is required f the fol- 
lowing processing occurs. 

The length of the record to be PUT is 
obtained either from the DCB, or, if the 
record is variable format and the PUT is in 
move mode, from the length control bytes in 
front of the record. If variable, the 
length is checked for validity -- at least 
equal to the number of control bytes CO, 1, 
<4 r or 5), but no greater than the maximum 
for records of its type. An invalid length 
causes abnormal termination of the task« 

For local devices, a record of the 
obtained length will not fit in the space 
remaining in the buffer, end-of-buf f er pro- 
cessing must be done before the current 
record can be processed, and control is 
transferred to a section for invoking MSAM 
Read/Write. If the maximum size record 
will fit within the buffer, and if the POT 
is in locate mode, the current record 
address is set into register 1, the return 
code is set to zero to indicate normal com- 
pletion and control is returned to the 
user. If the PUT is in move mode, the 
record in the user-specified area whose 
address was supplied in register is moved 
to the current buffer location. 

For RJE fwhich operates only in locate 
mode! , buffering is handled differently 
than for local devices* Ixxjicai records 
are built into transmission control blocks 
CTCBs) aligned on halfword boundaries 
within the page buffer* The page buffer 
and DECB work page both contain appropriate 
pointers and flags Ccurrent TCB pointer, 
final TCB flag, etc.). The address pointer 
returned to the caller does not point to an 
area in the page buffer itself, but rather 
to a lau-byte area within the DECB work 
page* DOMSAM then processes the record 
from this location, moving it to the cur- 
rent TCB in the page buffer after it has 
been processed. On normal completion, the 
address of the record buffer in the DECB 
work page is returned to the user in 
register 1. 



Additional processing depends on whether 
or not the TCB is filled, whether it is the 

final TCB in the page buffer, and, if not, 
whether there is sufficient space in the 
buffer for another TCB of maximum (40*4 
bytes) or minimum C27B bytes) length* 
Appropriate flags are set; if an end-of~ 
buffer condition is reached, MSAM Read/ 
Write is called* If the RJE device has the 
multiple record feature CMRF), seven reco- 
rds may be placed in a TCB? otherwise, two* 
If necessary, the 'Previous Put in Locate 
Mode* flag is set on before returning to 
the user. 



If for both local and RJE, the previous 
PUT was in locate mode, the record subse- 
quently built in the buffer requires check- 
ing- if variable format records are being 
used, the length is checked for validity as 
above and also for being no greater than 
predicted. If the DCB indicates that this 
is a form-sensitive file for a local or re- 
mote printer, the control character is 
tested, A machine code control character 
specifying "'skip to Channel 1 after print® 1 
will trigger the ending of the current 
buffer after this record- A FORTRAN CASA) 
control character specifying ^skip to chan- 
nel 1 before print* will result in the new 
page switch being set in the associated 
DECB as this is the first record in the 
buffer, or will trigger processing to end 
the buffer in front of this record if it is 
not. 

For RJE tasks, RJE transmission control 
characters are inserted into each record, 
and a dummy record is moved to the TCB 
where this is the first PUT after OPSi or 
FINISH, or if this is the first record in 
the buffer and it has FORTRAN CASA) control 
characters . Trailing blanks are sup- 
pressed; error characters are translated 
from the record? if tabbing is required, 
tabs are inserted in the record; and the 
FORTRAN CASA) or machine control character 
is translated to a 2780 control character. 
The processed record is then moved from the 
144-byte record buffer in the work page to 
the current TCB in the page buffer and the 
TCB length is adjusted* If FINISH is in 
progress, an end-of -transmission TCB is 
added to the buffer* 

In all cases, once the logical record is 
satisfactorily placed in the buffer, the 
current record address is incremented by 
the record length to point to the next 
available space in the buffer. If variable 
length records are being processed, the 
total block length is also incremeented by 
the record length. !he count of records 
within the block is incremented by one, and 
if it has reached the output buffer maximum 
of 2 00, the end-of -buffer switch in the DCB 
is set on so that the next PUT processed 
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will cause end- 
occur. 
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Then, If processing 01 a move-mode PUT 
has just been completed, control is 
returned to the user with a return code of 
zero indicating normal completion. If, 
however, the previous processing has com- 
pleted checking of a previous lecate-mode 
PUT f control is transferred back to the 
beginning of the PUT routine, where the 
end-of -buffer switch is tested before pro- 
cessing the current PUT. 

When a buffer roust be ended and written 

out before the next record can be pro- 
cessed, the appropriate switches are set, 
and control is transferred to a section for 
invoking MSAM Read/Write. This section 
will check to see if Read/Write has already- 
been invoked, and if so, will proceed to 
test the appropriate DECB for completion™ 
If complete, control is returned immediate- 
ly to the caller (MSAM FINISH). 

If Read/Write has not yet been invoked, 
and if a FINISH macro instruction was not 
issued just prior to this PUT, the current 
record count is set into the DECB and then 
reinitialized to zero. The DECB is marked 
read/write requested, and MS AM Read/Write 
is given control. Upon return from Read/ 
Write, the pointer to the current DECB is 
updated to point to the next DECB, unless 
the current DECB is the last in the list, 
in which case the pointer is reset to point 
to the first DECB in the list. The DCB 
pointer to the current buffer page is set 
to the buffer address associated with the 
current DECB, and the pointer to the DECB 
to be tested for completion is set. In an 
RJE task, TCB flags and pointers are 
initialized in the buffer and DECB work 
pages. 

Once MSAM Read/ Write has been invoked, 
the DECB is tested for completion. If it 
is not marked complete, the next record may 

not be processed, and control is returned 
to the user with a return code indicating 

incomplete. Where incomplete because an 

RJE line is disconnected, before returning 
to the caller, a return code is set to ind- 
icate RJE intervention is required. 

If the DECB is marked complete # a check 
is made for an unrecoverable I/O error, and 
if one is found, a test is made to deter- 
mine if the error was non- permanent and 
already returned to the user. In that 
case, provided no lORCBs are still out- 
standing (in which case a code of incom- 
plete will be returned to the caller) , MSAM 
Read/Write will be called to output the 
records suppressed by the error, and the 
DECB will be tested again for completion, 
if the error was not already returned to 
the user, the DECB associated with the 



error is located and moved to the user's 
DECB area. Thr- address of the failing 
record is computed, and control is returned 
to the user with a return code indicating 
unrecoverable I/O error. If the proper 
DECB could not be found, it is assumed that 
error recovery is still in progress , and 
control is returned to the user with a 
return code indicating incomplete. 

If no I/O error occurred and the finish- 
in™ progress flag is on, control returns to 
the Finish routine. Otherwise, if no I/O 

error occurred, a check is made to deter- 
mine if the new buffer begins a new form- 
sensitive print page. If so, and if FOR- 
TRAN (ASA) control characters are being 
used, the record which should start the new 
page is still trailing after the last reco- 
rd in the buffer just written and must be 
moved to the beginning of the current buff- 
er. If the new buffer does not begin a new 
form-sensitive print page or FORTRAN CASA) 
control characters are not used, the first 
available location in the buffer is set 
beyond the 32 control byt?s. If the reco- 
rds are variable format, this address 
points to the block control bytes (LL) 
which are then Initialized to four, and the 
first available location address is incre- 
mented by four. For RJE, this address 
pointer is further incremented by 12 to 
allow space for the printer selection 
sequence and various bisynchronous charac- 
ters. The address of the first available 
location is saved in the DCB as the current 
record address, and control is transferred 
back to the beginning of the Put routine to 
process the current PUT. 

If, upon entry to the Put. routine, a 
FINISH macro instruction has just been 
issued and end-of- buf f er processing is 
indicated, the following edits and initia- 
lization, largely of the type performed by 
MSAM Open, are required before the Put can 
be processed. 

If any permanent I/O errors have 
occurred, or if any lORCBs remain outstand- 
ing, the task is abnormally terminated. If 
none, a switch is set in the DCB to indic- 
ate that this is the first PUT on this data 
group, and the various processing switches 
in the DCB are reset. All DECBs are rein- 
itialized, the pointer to the current DECB 
is set to point to the first DECB in the 
list, and the current buffer page address 
is set from the current DECB. The record 
format is checked to be certain it is eith- 
er fixed or variable, and if it is neither, 
the task is abnormally terminated. The 
current record address is computed as 
described above. In an RJE task, TCB 
pointers and flags are reinitialized and 
maximum and minimum TCB size is set. 
Abnormal termination occurs if the device 
is neither a card punch nor a printer, or 
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if the logical record length specified in 
the DCB is invalid. Otherwise, conrol is 

transferred to the beginning of the PUT 
routine to process the first record of the 
new data group. 



MGAM R ^ad/Write Routine (C2CMF) 

The M5AM Read/Write routine builds an 
10RCB # which contains a channel program 
(CCWs) to process an entire buffer page of 
records. It invokes IOS by the IOCAL SVC 
to perform the actual input or output com- 
mands. (See Chart BO) 



Attributes : Privileged, read-only, public, 
reentrant, nonrecursive. 

Entry Point : CZCMF1 -- Entry from DOMSAM 
(GET or PUT) by type-1 or type-2 linkage. 

Input : Register 1 contains the address of 
the DECB. 



If the DECB passed to Read/Write indi- 
cates a READ/WRITE request, the IORCB is 

built and executed. The location of the 
buffer page is placed in the single page 
list entry. All CCWs created will 
reference this page list for the address of 
the buffer page. Pointers , counters, and 
the displacement are initialized. Each CCW 
contains a displacemnt field which corres- 
ponds to the displacement, in its buffer 
page, of the data to which this CCW refers. 
If the CCW does not reference data (for 
example* skip immediate or NOP) , the dis- 
placement is the same as for the adjacent 
CCW. The device type is tested, and pro- 
cessing diverges for local or remote 
devices, and for input or output. 

For local card readers t the data mode 
(EBCDIC or column binary) the stacker bin, 
and the record length are determined from 
the DCB. Two command- chained CCWs are 
generated for each record to be read; a 
read CCW followed by a feed and select 
stacker CCW, 



Data References : CHADEC f CHADCB, CHADEB, 
CHAIOR, CHAISA. 

Modules Called : 

DIR CCZCJD) -- Delete interruption routine* 

IOCAL (CEAAG) -- Initial supervisor proces- 
sing of an IORCB. 

SYSER CCEAIS) — System error processor. 

Reset (CEAAH) -- Reset device suppression 
flag routine. 

Exit s: 

Normal -- No return codes used. 

Error — - Link to ABEND with condition code 
1 and appropriate error message. 

Operation : When Read/Write is entered, the 
DCB address, the DEB address, and the 
address of the buffer page are obtained 
from the DECB- The location where the 
IORCB is to be built is obtained from the 
tirst system control word of the buffer 
page. Since this buffer page may be in 
Class A C user read-write) virtual storage, 
a series of checks are made to verify trutt 
the IORCB address is still valid and has 
not been changed by the user. An incorrect 
JORCB address causes an ABEND. 

If the DECB passed to Read/Write indi- 
cates complete with error rather than Read/ 
Write request, any outstanding asynchronous 
routine is deleted, the IORCB abnormally 
terminated is reissued immediately at a 
point beyond the command that failed, and 
any subsequent lORCBs whose DECBs are 
marked intercepted are reissued. Control 
then returns to the caller* 



After the CCWs have been constructed for 
a buffer full of records C count is given in 
the DECB) , a NOP without command chaining 
terminates the CCW list. The length of the 
CCW list and the total length of the IORCB 
are computed and set in the fixed area of 
the IORCB. 

If this is the first record of a data 
group f or on initial priming after an 
error, the device is reset for I/O and 
exceptional condition flags are cleared, 
(If not the first record, and an exception- 
al condition has been detected on the 
device, the DECB is marked "'posting reis- 
sue" if error recovery is in progress, or, 
if not in progress, it is marked ^inter- 
cepted", and control returns to the 
caller - ) 

Task interruptions are inhibited while 
the count of lORCBs outstanding is incre- 
mented by 1. Then this IORCB is issued to 

IOS by executing its IOCAL SVC. Control is 
returned to the calling program. 

For remote card readers, an IORCB is 
built consisting of alternating read and 
write CCWs, Each read CCW brings in a lb 8- 
byte transmission containing two card reco- 
rds. With a remote card reader containing 
the multiple record feature, each read CCW 
will bring in four card records. Following 
each read CCW a two™ byte write CCW is built 
in the IORCB to transmit to the device ack- 
nowledgement of the previous read. The 
write CCW transmits bisynchronous control 
characters CACKO or ACK1) which must 
alternate for successful transmission- For 
purposes of error recovery, the first CCW 
built in the IORCB will be a one- byte write 
containing a negative acknowledgement 
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character (NAK) . This will be followed by 
a NOP command, then an initial write CCW 
with an acknowledgement character. The 
start CCW will follow and be the first of 
the alternatinq read and write CCWs built 
in the IOKCR. 

A paqe buffer in <m RJ E GET operation 

may contain up to 24 transmissions (48 card 
records) . when the maximum number of CCWs 
have been reached (or there are no more 
records) , a NOP command will terminate the 
command chain* The lengths of the CCW list 
and of the IORCB are computed and entered 
in the fixed area of the IORCB. 

If no errors ere outstanding, acknowled- 
gement responses for the write CCWs are 
synchronized, task interruptions are per- 
mitted if necessary , and the IORCB is 
executed via the IOCAL SVC. Control is 
returned to the caller. 

For card punches and local or remote 

printers both FORTRAN (ASA) and M control 

characters are supported* The record 
length for fixed length records is deter- 
mined from the DCB- Variable length reco- 
rds specify their own length. The length 
field of a variable length record is never 
printed or punched nor is any control 
character printed or punched. Control 
bytes are examined in the buffer. 

If the device is a card punch, one 
punch* feed, and select stacker CCW will be 
generated for each record to be punched. 
If M control characters are being used the 
control character itself is used as the 
command code. It must be a write command, 
otherwise ABEND terminates the task. If 
FORTRAN (ASA) control characters are being 
used, the command code is determined by 
combining the DCB mode specification with 
the appropriate extended ASA stacker speci- 
fication. If no control characters are in 
use, the mode and stacker specifications 
are obtained from the DCB and combined to 
create the command code. If COMBINE is 
specified, the stacker must be RP3, other- 
wise ABEND terminates the task. 

If the device is a local printer and if 
universal character set (UCS) printing is 
to be done a reset block data check command 
is the first command of a data group. Pre- 
ceding the first print command of a data 
group is a skip immediate to channel 1 CCW. 
If neither FORTRAN nor M control characters 
are in use, each CCW created to print a 
line will be a write and space after writ- 
ing* The number of lines to space is 
determined from the DCB. If M control 
characters are in use each control charact- 
er will be used as the command code in the 
one CCW generated for each record. It must 
be a write command, otherwise ABEND will 
terminate the task. Since FORTRAN control 



characters specify skipping or spacing 
before printing as opposed to the command 
codes which specify only skipping and spac- 
ing alone, or skipping or spacing after 
printing, the control action is associated 
with the previous write, or requested a] on* 
if there is no previous write. Thus, if" 
FORTRAN control char act err; are in use, the 
first record will cause two CCWs to be con- 
structed; one control ccw to skip or space 
before printing and one write CCW. Each 
subsequent record will cause the generatior 
of one CCW, whose write command code is 
also determined by the next FORTRAN control 
character. The CCW for the last record to 
be printed is a print and no space command. 
When the last punch or print CCW has been 
built, the list is terminated with a NOP, 
and the line of processing for the card 
reader is rejoined. 



If the device is a remote printe 
channel program will consist of alt 
write and read CCWs. Each write CC 
transmit, a transmission control bio 
of data containing up to 7 records 
device has the multiple record feat 
2 records if it does not. Each rea 
will read in bisynchronous acknowle 
bytes for determining successful tr 
sion (alternating ACKO and ACK1). 
is the first PUT after an OPEN or F 
macro instruction, or if the IORCB 
reissued for purposes of error reco 
the initial CCWs will consist of wr 
reads of bisynchronous bytes to asc 
the state of the device and get the 
ledgements (ACKO and ACK1) in synch 
tion and a selection record to self 
printer. In addition, if the devic 
the tabbing feature, CCWs will be a 
write the tabbing record, which wil 
the tabs on the printer. (The 1 4U- 
tabbing record is built by Read/Wri 
the IORCB preceding the page list p 
it is built only once for each IORf 
write/read CCW pairs will follow ur 
end-of -transmission (EOT) TCB is r< 
gnized. Then a write CCW is built 
EOT TCB and a NOP is added to termi 
command chaining. 

TAM Read/Write Routine (CZCYM) 
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During the execution of a systen, pro- 
gram, where the programmer had oricinally 
requested a read or write from or to a ter- 
minal, a call is generated that lirks to 
TAM Read/Write. 

TAM Read/Write functions are accomp- 
lished by using the control blocks and 
buffer area allocated during TAM Open, and 
by using the tables internal to TAM Read/ 
Write. The terminal-computer communicatio: 
is accomplished through a buffer area undet 
control of the channel command words 
(CCWs), located in the IORCB. 
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TAM Read/Write also issues control func- 
tions (orders) to the transmission control 
unit (2702). (See Chart BD. ) 

Attributes: Reentrant, resident in virtual 
storage, closed # read-only, privileged. 

Entry Points : 

CZCY^P^^^fype-- 1 linkage. Entered from 
systems routine. 

CZCYM2 — Type-1 linkage. Entered from TAM 
Posting, 

Input : Register 1 contains the address of 
the DECB. 

Data Reference : CHADEC, CHADCB, CHA'OEB, 
CHAiOR, CHATOS, CHASDA. 

Modules Called; 

mEUD^Tc^^FT""'- Abnormal task termination. 

CKCLS (CJSAQ4) -- Check protection class. 

iOCAL CCEAAO) -- I/O call. 

TSEND (CEAP9) ~ Time slice end. 

Exits : 

Normal — • Return to calling routine. 

Error — ■ ABEND macro instruction . 

Operation ; TAM Read/Write initially saves 
the general registers. The general regis- 
ters are then loaded with pointers to 
referenced control blocks, starting with 
the data event control block (DECB) ; 
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The DECB pointer to the DCB is included 
as one of the Read/Write macro instruction 

operands. The rest of the pointers are 
described in TAK Open. 

An initial test is made to see if a non- 
privileged user has called TAM Read/Write. 
An improper linkage will immediately ABEND 
the task. 

Any time the command system is used* it 
causes TAM Read/Write to be invoked oy way 
of the Gate routine, Nonpriviieged pro- 
grams should only use those GATE macro 
instructions which link to the Gate rou- 
tine. The system program Gate routine then 
links to TAM Read/Write. A nonprivileged 
program attempting to directly call TAM 
Read/Write is an abnormal condition that 
causes a branch to ABEND. Two areas of 
error testing are then made to assure that 
system parameters are properly set. If 
either area is not satisified f a return to 
the user occurs* If both areas are 
correct, TAW Read/Write continues. 



The first area tested assures that in 
the SDAT the number of active lORCBs is 

zero. No busy DECB exists for this termin- 
al. (A busy DECB occurs after a TAM READ/ 
WRITE is issued and ends during tne corres- 
ponding TAR Posting.) If the number of 
active lORCBs is zero, the IORCB active 
count field in the TAP Read/Write PSECT for 
this terminal is set to 1 (for this TAh 
Read/Write entry) and the second area is 
tested. If the number of active lORCBs is 
not zero, then the in™ use bit in the flag 
field of the DECB is set ana a return is 
made to the user. 

The second area tested assures that in 
the DECB f the type option code specified is 

within the range of all defined types for 
ail terminal types, and that the type 
option code specified is valid for the 
actual terminal type. 

it these conditions are met, data from 
referenced areas, including DE3 informa- 
tion, are merged in TOS (terminal access 
operational status table) to reduce paging 
time later- The type option is then 
decoded. 

it either of these conditions is not 
met, no further testing occurs. Instead, 
an error code is moved into the ECB of the 
DECB f the user error flaq is set in the 
DECB and the SYNAD request is set in the 
DECB. A return to the user occurs. 

The type option code in the DECB is then 
decoded to see if it is a control function 
(order). If it is a control function; 

• The corresponding CCW generator 
generates one appropriate CCW in the 
TOS ouild area. 

• The CCW is moved from the TOS build 
area into the IORCB CCW list area. 

• The IORCB fixed area is completed. 

• An IOCAL is issued, which links to IOS 
for this IORCB to be executed. When 
the supervisor returns control, TAM 
Read/Write restores the registers ana 
returns to its user. 

Accessing the Channel Program Generator : 
If this is not a control function, TAh 
Read/Write begins processing to build a C'.'w 
list appropriate to the option requested 
for the particular terminal. 

TAM Read/Write begins processing for 
this requested terminal computer I/O opera- 
tion by first finding the proper channel 
program generator (CPG) . To accomplish 
this a program search of internal tables 
within TAM Read/Write (illustrated in 
Figure 6) is required. These tables are: 
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TAM Read/Write: CPG Location Sequence 



CPG - TIA (W) 




• The unit type table (UTT) 

• A terminal library table (TLT) 

• A terminal channel program (TCP) 

The procedure to find this CPG in TAM 

Read/Write requires as input: 

• Terminal information loaded in the DEB 
from the SDAT during TAM Open contain- 
ing terminal type and model code (refer 
to Table 8) . 

• Type option code specified in the DECB 
(refer to Table 9). 

The sequence (refer to Figure 6) in 

finding this CPG is as follows: 

1. The code for the mechanism for joining 
the terminal to the system (that is, a 



2702 control unit connection or a 
direct multiplex connection) deter- 
mines the displacement in the UTT to 
obtain the address of the TLT (Table 
10). 



The model code (that is, 1050 or a 
27*41) determines where in the TLT 
(refer to Table 11) the address of the 
TCP can be located- This address is 
then examined. 

a. If the entry in the TCP is zero, 
it indicates that the library does 
not exist. 

b. If the TCP entry is an address, 
TAM Read/Write then calculates a 
displacement from the TCP, which 
is used to get to the appropriate 
CCWG. 



Section 3: Read/Write 37 



Table 8. TAM Read/Write: Terminal Inter- 

ma t i on f rom S DAT 
r — T __ T _. . . ,_ T „_ 1 

Model | Line | Terminal { SAD 

Code j Type | Type (Order 

j | High-Orderj Low-Order | 

Byte ljPyte 2| Byt^ 3 1 Byte 3 (Byte *4 

Byte 1 -- represents a model code for 
terminal units (1050, 2741 # 35, 1052) 

Byte 2 -- represents a line type for 
connection (dial line or dedicated line) 

High-Order Byte 3 -- represents a 
terminal control unit type (IBM terminal 
control unit; type I, type II, telegraph 

terminal control unit; type I # type II , 
World Trade terminal control unit) 

Low-Order Byte 3 -- represents a terminal 
channel connection type (2702 # 
Multiplexer) 



Byte H 
2, 3) 



represents a SAD order (0 # l f 



3. In tne TCP (Table 12), TAM Read/Write 

locates the proper CPG from the type 
option code. The TCP is divided into 
three main fields which are; 

• Terminal control information table 

(TCIT) 

• Channel program index 'table (CPIT) 

• Channel program generator (CPG) 

The terminal control information table 
(TCIT) in the TCP contains data on addres- 
sing, polling , EOL sequence characters, 
etc. # (Table 13) . 

The channel program index table (CPIT) 
(refer to Table 12) determines from the 
Type option code (stripped of the repeat 
bit if any) where the corresponding CPG 
displacement is. 

The CPG is obtained from the displace- 
ment in the CPIT. This displacement value 
is added to the TCP address to generate the 
address of the CPG (Figure 6). 

Makeup and processing of the Channel 
Program Generator: A CPG contains channel 
command word generators (CCWG) (refer to 
Table l«*). 

A breakdown of each of the CCWG sections 
is shown in Table 15. 

To process the CPG, each sequence cycle 
begins by sequentially testing the CCWG 



buffer allocation flag bits shown in Table 
16. For each flag that is on, TAM Read/ 
Write branches to the indicated associated 

routxne to perform the indicated required 
function. These functions are used in 

generating a CCW or updating information 
needed to construct an IORCB. Overall 
these functions include allocating space in 

the IORCB buffer area and moving into this 
buffer: 



• Begin and/or end control characters 

• Space for response characters 

• Output data 

• Data translation of output data 

• Space allocation of output data 

The last buffer allocation flag is an 
end flag. If it is not set, the developed 
CCW is then moved (see note below) Into the 
build area of TOS where the command code 
and flag fields are obtained from the CCWG 
area and the count and relative displace- 
ment address fields are obtained from regi- 
sters. The logical function code is moved 
into the logical function area of TOS to be 
used later by TAM Postinq. The next 
sequence cycle in this CPG then repeats, by 
sequentially testing the next CCWG buffer 
allocation flags, 

If the last buffer allocation flag is 
set, TAM Read/Write prepares to terminate. 



Note : A developed CCW is not moved into 
the build area of TOS and the logical func- 
tion byte code is not moved into its respe- 
ctive location if the following conditions 
are present in the CCWG: 

• Command code field is zero 

• End allocation flag is set 

• Inhibit allocation flag is set 

TAM Read/Write then prepares to termin- 
ate since ail the allocation flags in all 
the CCWGS in the CPG have been tested. To 
accomplish this termination; 

• The message in the buffer area of the 
IORCB is translated to the terminal 
character set code, for all write 
operations. 

• The CCW list is moved from the TOS 
build area into the IORCB CCW list 
area, 

• The IORCB fixed area is completed. 
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Table 9. TAM Read/Write: Type Option (Hex and Mnemonic) Codes and Description 
(Part 1 of 2) 



| Opt ion 
Code 
(Hex) 



Mnemonic 

Option 

Code 



Descr iption 



02 



03 



06 

07 
08 



09 
0A 

0B 
0E 



OF 



64 



65 



66 



TID 



TDR 

TIN 



i 



5 jTNR 



TCN 

TCR 

TID 



TDR 

TIN 

TNR 
TIA 



TAR 



AUTOWRAP 



DISABLE 



ENBLASYN 



Read Initial with Dial ; This option indicates that an automatic dial 
connection is to be made with the terminal. The dialing digits are 
located in the terminal entry list (DFTRMENT) . If the terminal type 
requires polling, the necessary polling sequence characters are 
generated. 

Read initial with dialing/repeat. 

Read Initial : It assumes that the line connection has been previously 
made. If the terminal type requires polling, the necessary polling 
sequence characters are generated. 

Read initial/repeat. 

Read Continue : This option is specified when polling is not required. 



It may be used for terminals previously polled and in a transmit state. 

Read continue/repeat. 

Write Initial with Dial s This option indicates that an automatic dial 
connection is to be made with the terminal. The dialing digits are 
located in the terminal entry list (DFTRMENT) . If the terminal type 
requires addressing, the necessary addressing sequence characters are 
generated. 

Write initial with dialing/repeat. 

Write Initial : It assumes that the line connection has been previously 



made. If the terminal type requires addressing, the necessary 
addressing sequence characters are generated. 

Write initial/repeat. 

Write with Response : It assumes that the line connection has been 



previously made. If the terminal type requires polling and addressing, 
the necessary sequence characters are generated. This option provides 
the ability to output a message to a terminal and receive the 
terminal's next input record or line. The maximum output message size 
is 1 to 32,767 characters. The maximum input message is one logical 
record or line as specified by terminal type. 

Write with response/repeat. 

The above types with the repeat option will automatically retransmit or 
request retransmission of messages in error if the terminal is equipped 
with error correction facilities. A predetermined number of retries as 
specified by terminal type will be attempted for each message 
transmitted in error. The posting of uncorrectable errors will include 
appropriate error inf ormatior . 

On accepting this order, the Transmission Control Unit wraps the output 
of the addressed line to the input of line 0. The command within the 
channel operates as a write. 

On accepting this control order, the Transmission Control Unit resets 
the enable latch within the line adapter of the addressed 
communications line. No data transfer occurs. 

On accepting this control order, the Transmission Control Unit sets the 
enable latch within the line adapter of the addressed communication 
line. No data transfer occurs. 
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Table 



Option 
Code 

(Hex) 



TAM Read/Write; Type Option (Hex and Mnemonic) Code^ 
(Part 2 of 2) 



and Description 



,.„„„+„„„„+ „„_„__ „„_. _. 



67 



68 



69 



6A 



6B 



6C 



6A 



Mnemonic 

Option 

Code 



ENBLSYN 



PREPARE 



Description 



-H 



On accepting this control order, the Transmission Control Unit sets the 
enable latch within the line adapter of the addressed communication 
line. No data transfer occurs. 



This order may be used in a con 
indicate to the processor when 
bit is detected by a line instr 
off. If at stop time the line 
terminated with channel end and 
assembled is not transferred to 
is at space, a timeout is start 
the timeout is complete, the pr 
end and device end. The prepar 
occurs, indicating an open line 
and unit check status and inter 



tention type communications system to 

data is arriving. When a valid start 
ucted to prepare, a character is strobed 

is at mark, the prepare command is 
device end status. The character 
the multiplexor channel. If the line 
ed. If the line returns to mark before 
epare command is terminated with channel 
e command is terminated when the timeout 
condition with channel end, device end, 
vention required in the sense byte. 



SADONE | On accepting this control order, the Transmission Control Unit sets the 
terminal control CTC) field within the addressed LCW to one, so that 
the terminal control with the internal address equal to one is 
associated with the addressed communications line. No data transfer 
occurs. 

SADTWO | On accepting this control order, the Transmission Control Unit sets the 
TC field within the addressed LCW to two, so that the terminal control 
with the internal address equal to two is associated with the addressed 
communications line. No data transfer occurs. 

SADTHREE|On accepting this control order, 'the Transmission Control Unit sets the 
TC field within the addressed LCW to three, so that the terminal 
control with the internal address equal to three is associated with the 
addressed communications line. No data transfer occurs. 

SADZER | On acceptance, the Transmission Control Unit will set the TC field 

within the addressed LCW to zero so that the terminal control with the 
internal address equal to zero is associated with the addressed 
communication line. No data transfer occurs. 

BREAK | On accepting this order, the addressed line transmits a continuous 

space signal. Bytes transferred from the channel to the addressed unit 
must be all zeros. To provide control over the length of space signal, 
a byte count must be sepecified by the program. 



Table 10. TAM Read/Write; Unit Type Table 
Format 



r _ — . _ — „ .„_„„ — „^-„-.-„_-..„ 1 

|2702 TERMINAL LIBRARY TABLE CTLT) ADDRESS 

1 

|2701 TLT ADDRESS 

I 

| MULTIPLEXER TLT ADDRESS 

1 

i SELECTOR TLT ADDRESS 

I 

|2701 OR SELECTOR TLT ADDRESS 

j Note s Unit Type Table CUTT) is specified 
| in READ/WRITE. 



Table 11. TAM Read/Write: Terminal 

Library Table Format Cfor 270 2 
TLT) 
r „— . ._„_ — _ — .-. — ._ . — . — .. — . _. — .„-.„- 

|1050 TERMINAL CHANNEL PROGRAM (TCP) 
l ADDRESS 

i 

|2741 TCP ADDRESS 

| 3 5 TCP ADDRESS 

L. . . . . . „_J 
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Table 12. TAM Read/Write; Terminal Con- 
trol Program Format 



r 


TERMINAL CONTROL INFORMATION TABLE 








CHANNEL PROGRAM INDEX TABLE (CPIT) 



CPG DISPLACEMENT FOR TID* CR> 

CPG DISPLACEMENT FOR TIN* CR) 

CPG DISPLACEMENT FOR TCN* (R) 

CPG DISPLACEMENT FOR TID* <W) 

CPG DISPLACEMENT FOR TIN* (W) 

CPG DISPLACEMENT FOR TCN* (W) 

CPG DISPLACEMENT FOR TIA* <W) 



CHANNEL PROGRAM GENERATOR for TID* (R) 

CPG FOR TIN* CR) 

CPG FOR TCN* (R) 

CPG FOR TID* CW) 

CPG FOR TIN* CW) 

CPG FOR TCN* CW) 

CPG FOR TIA* CW) 



♦All CPG displacements need not be 
required for the terminal type. These 
displacement fields are zeroed and the 
corresponding CPG fields do not exist. 



* An IOCAL is issued, which links to the 
supervisor to initiate the terminal 
computer communication, under control 
of the IORCB CCW list and through the 
IORCB buffer area. 

When the supervisor returns control, TAM 
Read/Write restores the registers and 
issues a return to the user, if the posting 
flag is not on. 

If the IORCB buffer data area was not 
large enough to complete the TAM Read/Write 
operation t it is necessary for continuous 
lORCBs to be developed for one DECB. 
Although the initial TAM READ/WRITE was 
from the user, subsequent IORCB entries 
would be from TAM Posting until the opera- 
tion is complete. These TAM Posting calls 



Table 13. TAM Read/Write: Selected Ter- 
minal Control Information Table 
Entries 

r . _ . — . 1 

Maximum Option Amount; Begin Control 
Character Count; Begin Control Character.! 

Maximum Cnaracter ^>et Amount; Polling ■ 
Character Count; Pollinq Characters. 

Prefix Count; End Control Character 
Count; End Control Characters. 

Read End Of Line Sequence Count; Redd End 
Of Line Sequence Character. 

Maximum Number of CCW; Addressing 
Character Count; Addressing Characters. 

TAM READ Data Set Length; Control 
Character Table Address. 

Write Error; Read Error; Read Error 
Positive Response. 

Control Count; Positive Response; 

Characters. 

Maximum Count Of Line Control Characters; 
Read Error Negative Response; Read Error 
Negative Response Characters. 

TAM WRITE Data Set Length. 

Polling Response; Addressing Response 
Count; Addressing Response Characters. 

Repeat Option; End Of Line Sequence 
Count; End of Line Sequence Characters 
(20 Characters Maximum). 

Maximum Buffer & CCW Size; End of Card 
Sequence Count; End of Card Sequence 

Characters. 

Terminal Character Set Address; Translate 
and Test Function Table Address. 

Continue Count; Text Control Character 
Count; Text Control Characters. ) 

i 

Failure Count; End of Message Sequence \ 
Count; End of Message Sequence Characters! 
(20 Characters Maximum). j 



to this program cause a return to TAM Post- 
ing under direction of the posting entry 
flag in TOS. 

XQREQ Routine CCZCSB) 

During the execution of a user's pro- 
gram, where the programmer had originally 
issued an IOREQ macro instruction to gener- 
ate an I/O operation on a device, a call is 
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Table 14. 



Name 



TAjM Read/Write: Channel Command 
Word Generator Section 

T „ _. _ — _ 1 

I Comments I 



Table 15. TAM Read/Write: Channel Command 
Word Generator Format 



Command Code 

Field 



Unused Field 



Displacement 
Field 



Command code for a particu- 
lar operation. This byte 
is moved into the command 
code field of a CCW list 
located in the build area 
of TOS. 

This field is reserved for 
future expansion* 

Displacement of ending 
point to CCWG wnen 
completing a CCW or a 
regeneration of a 
particular command 
generator when multiple 
lORCBs are required. 

Flags required for a parti- 
cular command generator. 
Required for TAM Posting 
routine. The byte is moved 
into the logical function 
area of TOS. 

Required in building the 

CCW. Allows additional 
routines to oe called to 
fill in the buffer area of 
the IORCB when a CCWG is 
1 processed. 



generated that links to IOREQ. A system 
routine may also directly call IOREQ at a 
second entry point, 

IOREQ uses control blocks and buffer 
areas that are allocated during IOR OPEN to 
build channel command words in the IORCB. 
(See Chart BE. ) 

Attributes : Reentrant, resident in virtual 
storage, closed f nonrecursive, read-only, 

privileged. 

Entries : 

CZCSB1 -- Type- 2 linkage. Entered from 
user IOREQ macro instruction. 



Flag Field 
Logical Func- 
tion Code 
Field 



Buffer Allo- 
cation Flag 
Field 



r _ T 

I Command Code ISee 



Table 9. 



j Displacement (Completed by IOS 



i Flags 



[Logical Func- 
jtion Code 



[Buffer Alio- 
(cation Flag 



[Data chaining, command 
[chaining, suppress length 
(indication, skip, proaram 
jcontrol interruption. 

[Dial end control, data out, 
(data in, read error 
[response, write error 
I res pons 'i, addressing, 
(polling, d Idress response, 
(polling response, control, 
|end control, error TIC, 
[negative response, write 
(error message. 

See Table 16. 



The second parameter word is used only 
for entry at CZCSB2. 

Data Reference : CHADEC, CHADCB, CBADEB, 
CHAISA, CHAIOR. 

Modules Called : 

CKCLS (CEAQ4) — Check protection class. 

IOCAL CCEAAO) ~ I/O call. 

Exits: 



Normal -- Return to calling routine. 

Error -- ABEND macro instruction. 

Operation : A user originally issuing an 
IOREQ macro instruction enters IOREQ to 
edit the VCCW list. IOREQ initially saves 
the general registers and then loads them 
with pointers to referenced control blocks. 
This starts with the DECB. 




CZCSE2 -- Type-1 linkage. Entered call by 
system. 

input : Register 1 contains the address of 
a two-word parameter list: 

Word 1 — Address of the DECB. 

Word 2 -- Address of main storage furnished 
by the privileged user for IOREQ portion 
of DCB and for IORCB. 



The DECB pointer to the DCB is included as 
one of the IOREQ macro instruction 
operands, and the other pointers are 
described in IOR OPEN. IOREQ then performs. 
the following functions: 

• Validates user parameters. 

• Checks that the DCB identification is 
valid DCBID=*%*%. 
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Tablp 16. TAin Rtau/WritP: buffet Allocation Fid'} Bits ot CCWG 



i ts ( Name 



Comments 



56 



u nu^ed 

R'-qin Control 



Em control 



Text Control 



erved for future expansion. 

No control characters requited. 

Begin control ch<ii'<HlerH required h'tore {>ollinq 

c tun ,u-\ t-i ' a* obtained from tfu- Tc I ,-ind niov< v .i t< 



bid l*-i 



iltq is lint l.itt 
««.» 1 n CKAIoK. 



No control characters require!. 

End control characters required after polling or addressmq has* b^en 
initiated. Characters are obtained f rorr the TCI and moved to Duffer area in 
CHAIOR. 



t * 



an 



oht ■ 



Chri 

t r. 



q 


n re. 


i. 












r 


ec u i i 


€ 


1 . 


if 


ter 


end 


control 


I 


and 


fT 


JV< 




to 


buff 


er area 
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t he CHAIOR. 



Read Error K) r .itiVf; 
Responsi- 



Read Error Negative 
Response 



Writt Error 
Response 



Address ing 



Pol li nq 



Addressing Response 



Polling Response 



Continue 



No uata transmitted to terminal. 

Hat a to be moved 1 rora user area (address in CHAD ECO) to bulfer arr.i in 

CHAIQR Idata is tested tor function control characters). Function Control 

Cnaracters and related code:; which are not recognized by different terminal 

typ«-s are delated t rnm message when moved to the buffer at* a in rilAIOri. 

1 ran:; lat i nq a, it a to terminal character set code ls done at completion ot 

CHAJOK. 

No data t ra nsmi t ted to CPU. 

Data to be transmitted from terminal to CPU. A buffer area is nserved in 

the CHAIOR to accept the message. The ntessaqe is not tested for function 
control characters. Translating data to EBCDIC is accomplished ,n TAF. 
POSTING routine. 

No Read Error Positive Response characters required. 

Read Error Positive Response characters required after transmission of data 
to CPU. Characters are obtained from the TCT and moved to buffer area of 
the CHAIOR. 

No Read Error Negative Response characters required. 

Sead Error Negative Response characters required after transmission of data 
to CPU. characters are obtained from the TCI and moved to buffer area of 
the CHAIOR. 

No Write terror control characters required. 

Write Error control characters are transmitted by the terminal control unit. 
The count is obtained from the TCI and space allocated in the buffer area of 
the CHAIOR. 

No addressing required for a terminal. 

^ Addressing required, obtain addressing characters from the terminal entry 
'list (DFTRMENT-address located in DECB). if not present, addressing 

characters are obtained from the TCI. characters are placed into the buffer 

area of the CHAIOR. 

No polling required for a terminal. 

Polling required, obtain addressing characters from the terminal entry list 

C DFTRMENT-address location in DECB). It not present, polling characters are 
obtained from the TCIB. Characters are placed in the buffer area of the 
: HA I OR. 

No addressing response required. 

• Addressing required, obtain characters i rom the TCIB. Characters are moved 
into the buffer area of the CHAIOR. 

• No polling response required. 

• Polling required, obtain characters from the TCIB. Characters are moved 
into the buffer area of the CHAIOR. 

• Current cnannel command wcrd will be d€-veloped and placed into the build 
area or the c r. L " " o . 

- Inhibit curreri* "hannel command word from being developed. 

- Follow normal : -r^uence of CCWG operation. 

■ Normal sequence of CCWG is changed. It permits return to a previously 
executed CCWG. 

- Continue normal sequence of CCWG. 

- Terminates the CCWG list. 
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• Checks that the DEB i dent if ication is 

valid DEBIB^* (. 

• Stores address of DECB in DCBTMP (work 

area) . 

• Clears the fixed portion of the IORCB. 

• Clears the outstanding IOREQ requests 
(DECB Queue) if the DEB flag CDEBNF7) 
is set. This indicates that the pre- 
vious CHECK macro instruction caused an 
exit to SYNAD. Therefore while execut- 
ing the previous SYNAD routine the user 
must reissue desired purged DECSs. 

Note ; If either the DCB or DEB identifica- 
tion is not valid* an exit to ABEND occurs. 

Pre-edit checking now occurs and, if 
satisfactory , IOREQ begins the edit phase. 
This pre-edit checking includes the 
following: 

1, Check if the IORCB can be executed. 
If a previous operation set the DEB 
flag CDEBNF1) to indicate an inter- 
cepted error , the IORCB is marked 
intercepted and a return occurs. The 
IORCB cannot be executed at this time, 
but the DECB is entered in the queue 
and the IOREQ should be reissued by 
the user. 

2. Check if the DECB is valid. A return 
occurs if the DECB has any of the fol- 
lowing invalid conditions: 

• The DECB is in the wait state CDECB 
not ready) . 

• The DECB is in use CDECB active) . 

• The queue of pointers in the DEB is 
full (DEBNPC is exceeded). 

IOREQ then begins the edit phase. This 
edit phase consists of a preliminary pass 
through the VCCW list pointed to by the 
IOREQ macro instruction to determine the 
validity of the VCCWs. In addition, the 
amount of space required for the buffer or 
page list entries and the VCCW list is 
determined* 

If buffering is requested by the IOREQ 
macro instruction, the following pointers 
and counters are also initialized; 

• A pointer to the lowest address of a 
read request VCCW, used to determine 
the low- order buffer address needed for 

the read request. 

• A pointer to the highest address of a 
read request VCCW* used to determine 
the high-order buffer address needed 
for the read request. 



A counter containing the amount of 
buffer space needed in the lORCR tor 
read requests. For these i ead 
requests, the amount ot butter space is 
the contiguous difference between the 
high and low-address buffer pointers. 



Tests are ilso made in this edit phase 
to assure that chaining rules are not vio- 
lated. Chaining rules are listed in IOREQ: 
VCCW section of Assemble r User Macro 
Instructions , GC28-2004. If any rules are 
violated, a return to the user occurs. The 
user's program has been checked for validi- 
ty within IOREQ but a system program that 
calls IOREQ directly, enters at this second 
point and therefore is assumed to have the 
VCCW list built correctly without the need 
of editing. However, on IOREQ recognizing 
a system program entrance, it branches to 
the previous phase only to set up buffer 
addresses and values or to build page list 
entries. During this build phase a dif- 
ferent sequence is followed depending on 
whether or not buffering is specified. 

If buffering is requested: 

• The start address of the IORCB buffer 
is set. 

• The buffer total length is set. 

• The start of the CCW list is set. 

The CCW entries are generated in the 
IORCB using the VCCW list as input, and 
space is allocated in the buffer area. In 
addition, in write and control requests, 
data specified in the fields of the current 
VCCW are moved into the buffer. If the CCW 
is a transf er-in-channel (TIC) , the displa- 
cement address of the CCW is set to point 
to the desired CCW (displacement is from 
CCW origin) . 

If buffering is not requested by the 
user, the appropriate addresses in the 
IORCB are set from values calculated in the 
edit phase (the previous pass through the 
VCCW list). The number of page list 
entries is calculated for the privileged 
request by a special branch to the initial 
edit section. For read, write* and control 
requests, the linkage is made from the CCW 
page list pointer to the appropriate page 
list entry, by searching through the page 
list for an address which has the same seg- 
ment and page in the CCW. 

For both buffered and nonbuffered 
IORCBS, the following also occurs: 

• The length of the IORCB is obtained by 
adding to the fixed area, the buffer 
area (either buffer or page list 
entries) , and the CCW list length. 



<*i* Part I: Access Method for BSAW, MSAM, TAM and IOREQ 



• The length ot the IORCB, if greater 
than the maximum allowed, causes IOREQ 
to return to the user with an error 
code in register 15. 

• This pass through the VCCW list moves 
the op-code count, and flag fields to 
the appropriate CCW list entry in the 

IORCB. 

• The protection key and other flags are 
set in the IORCB. 

The system programmer that entered at 
the second entry point now returns with a 
return code of zero in register 15. Hence 
to execute his IORCB* the system programmer 
must update the required fields and issue 
his own IOCAL, The sequence IOREQ follows 
for the IOREQ macro instruction user is: 



• Test the IOC flag in the last VCCW. If 
set, this IORCB must be chained to the 
next IORCB. 



• Move the DECB address into the queue by 
updating pointers to this DECB as well 
as updating the number of lORCBs and 
DECBs that are outstanding. 



Determine if the IORCB is not to be 
executed so that the DECB can be placed 
in queue and marked intercepted. 



• Issue the IOCAL macro instruction. 



• Return to the user. 
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SECTION 4: POSTING AND CHECK 



POSTING AND CHECK PROCESSING 

The following routines describe posting 
and error processing for SAM, SAM direct 
access, JYSSAM, TAM, and IOREQ f and the 
operation of the Check routine. 



SAM Posting and Error Retry Routine (CZCRP) 

This routine processes a synchronous I/O 
interruption caused by the termination of a 
SAM I/O operation. It posts the completion 
code in the event control block (ECB) of a 
data event control block CDECB). In addi- 
tion, depending upon tne device, this rou- 
tine may perform other post- I/O activities t 
such as adjusting magnetic tape block 
counts. The retry/ recovery operations are 
also incorporated into this routine; they 
are employed if the channel status word 
(CSW) returned at the roost recent interrup- 
tion reveals an abnormal end condition. 
(See Chart CA.) 



Attributes ; Reentrant, nonrecursive, resi- 
dent in virtual storage, privileged. 

Entry Point : CZCRP1 -- Main entry point 
via type-1 linkage. 

Input ; The channel status word (CSW) and 
sense information pertinent to the I/O 
operation are contained in the ISA. 

Data References : CHAD EC, CHADEB, CHADCB, 
CHAIOR, CHAJSA, CHASDA, CHASDT. 



Modules Called : 

VMER CC2RX2) — Virtual memory error 
recording. 

VMSDR CCZCRYY) — Virtual memory statistic- 
al data recording. 

ABEND CCZACP1) — Abnormal task 
termination. 

QLE (CZCJTQ) • — Build queue in task 
monitor. 

WTO and WTOA CCZABQ1) — Write message to 
operator. 



ASCII Translation CCZCWA1) 
ASCII data to EBCDIC- 



Translate 



DA Error Retry CCZCRH1) -- Direct access 
error retry routine. 



Reset CCEEAH) -- Permit task to access I/O 
device. 

SYSER (CEAIS) — System error processor. 

Exits : 

Normal -- Return to task monitor. 

Error -- An ABEND is issued if the I/O 

device is not tape or disk. A SYSER is 
issued if: 

* A program check has occurred. 

* A protection check has occurred* 

* A specification error has occurred. 

* The CSW has a status of X 8 00 f . 

* There was no entry for the SDA. 

* A command reject occurred because of 
an invalid op code. 

Operation : SAM Posting examines the com- 
pleted IORCB and either posts the DECB or 
passes control to a device- dependent error 
routine. 

Completion of the requested I/O is sig- 
nalled by the device via an I/O interrup- 
tion that is associated with the IORCB by 
the Supervisor. 

The completion information, along with 
the IORCB , is passed back to the requesting 
task as a synchronous I/O interruption 
enqueued on the TSI. During the interval 
between request and response, the task 
could have generated other I/O requests, 
and possibly had its time slice ended. 

SAM Posting requires that all interrup- 
tions be masked. It will process a synch- 
ronous 1/0 interruption to completion , 
regardless of the interrupted operation. 
SAM Posting will process only one synch- 
ronous I/O interruption at a time for a 
given task. 

The I/O Supervisor is expected to return 
unexecuted lORCBs when there is an I/O 
interruption caused by hardware failure, a 

unit check* or a unit exception condition, 

SAM Posting expects the following fields 
of the CHADEC Table CDECB) to be zeroed: 
ECB, BSJ, SB1, SB2 r FLG f CSE. Under error 
conditions, it examines BSF to determine 
how many sense bytes from the ISA are to be 
saved for user reference. These are placed 
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in the last field of the DECB (normally BSF 
will contain X f 02 , # indicating all eight 
sense bytes are to be saved) . 

For the Control routine (CNTRL) , IORCB, 
Rewind, and Rewind and Unload, the* DECB 
pointer in the IORCB will equal zero. The 
Check routine will clear the Error flag in 
the DEB to zero upon return from the user's 
SYNAD routine. 

In handling the I/O synchronous inter- 
ruption, the task monitor performs short 
save to provide working registers, and 
executes a type-1 call for the appropriate 
posting and error recovery routine. SAM 
Posting is the proper routine for SAM. 

SAM Posting first determines if the 
IORCB has been executed. An IORCB would 
not be executed if the preceding I/O opera- 
tion for that device had resulted in an 
abnormal completion. (Such a check must be 
done to handle error conditions properly 
when multiple lORCBs can be outstanding for 
one device by one task.) If the IORCB was 
not executed, the IORCB is reissued (via 
IOCAL) , or the DECB is posted to indicate 
"Intercepted" status. The choice depends 
upon whether the preceding condition was a 
permanent error. 



NORMAL COMPLETION : If the IORCB was 
executed, a test for normal completion is 
made. If normal, the event control block 
of the DECB is posted to indicate normal 
completion. SAM Posting also performs 
other optional services which can only be 
done after completion of the I/O operation: 

• Data Movement - Movement of data from 
an IORCB buffer to the user area for an 
input operation can be requested by the 
user. 

• Magnetic Tape Block Counts and Unit 
Exception Flag - SAM Posting increments 
(for forward tape movement) or decre- 
ments (for backward movement) the prop- 
er counts. The routine also sets 
appropriate flags for unit exception 
conditions. 

• Direct Access Read Variable Length 
Record and Pending C.W.E. Flags - The 
routine will perform the appropriate 
address movement and flag setting. 



OTHER THAN NORMAL I/O COMPLETION: 



IOS will 



lock the device to further I/O by this 
task, until a Reset SVC is issued by SAM 
Posting. This Reset SVC, when issued, will 
set off the suppression flag so that the 
task may resume I/O activity on the device 
in question. 



If the I/O was not normally completed, 
further tests are made and control is 
passed, if necessary, to device dependent 
error recovery routines which, if possible, 
will issue a retry I/O request. Each of 
these device dependent error recovery rou- 
tines subsequently returns to the posting 
routine. 

Unrecoverable (Hardware) Error Completion - 
General (non-device- dependent) Processing : 
If the CSW information associated with the 
executed IORCB does not indicate comple- 
tion, the routine searches for an immediate 
hardware indication of unrecoverable error. 

If the error or condition is rot yet 
considered to be unrecoverable, the routine 
will issue a Reset SVC to IOS. The purpose 
of the Reset SVC is to "unlock" the device 
queue previously "locked" by the I/O 
Supervisor. 

If the error is unrecoverable, the 
appropriate flags, addresses and counts are 
set. 

Recoverable Error or Exceptional Condition 
(non-Error) Completion - General Proces- 
sing : This condition is indicated by the 
Unit Check or Unit Exception flags. 

Recoverable Error or Exceptional Condition 
Completion - Device- Dependent Processing : 
If possible, depending on the device, N 
retries over the original path and also N 
retries over 3 alternate paths will be 
made, until a successful retry or until the 
set maximum of retries is reached- In the 
latter case the failure is termed a "hard" 
failure. The VMER routine is called to 
record data associated with this "hard" 
failure. 

Appropriate flags are set, messages are 
put out, counters are incremented, informa- 
tion is saved, and routine linkage is 

effected. 

Device- Dependent Error Procedures : The 
following are general notes on the device 
dependent error procedures : 

Error indication : When certain malfunc- 
tions occur, the CSW will contain more than 
one error indicator. Generally, only one 
of these properly describes the malfunction 
while the otherCs) indicate secondary 
effects. Similarly, some device/control 
Unit errors can cause more than one sense 
bit to be present. 

Original and alternate path retries : For 
some error conditions, there are no origin- 
al path retries. However, there are always 
alternate path retries. An original path 
retry utilizes the same channel and device 
as that used in the original erroneous I/O 
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operation. An alternate path retry uses 
the same device , but goes through a dif- 
ferent channel. 



N umber of retries : The number of retries 
is dynamic? the installation, however, not 
the user, determines the threshold number. 
In the descriptions of the error retry pro- 
cedures, in most cases N = a ♦ b wh€!re a is 
the threshold number, and b is a constant 
for that particular approach to recovery. 



User's SYNAD routine : If appropriate, SAM 
Posting will set the SYNAD flag in the 
user's DECB. The user's SYNAD routine is 
his own "error* routine. It does not, 
however 9 attempt error recovery on I/O 
devices, but rather determines if the user 
wants to terminate or continue processing . 



Return codes from error recovery routines: 

00 - Retry in progress, 

04 - Permanent error encountered, no 
retry. 

08 - Normal completion. 

OC - Complete with error without retry. 

10 - Complete with error after retry. 

Rebuild of the IORCB; 

The IORCB will be in page 0, segment 
of virtual storage (that is, within the 
interruption storage area). The issuance 
of an error retry IORCB will consist, in 
the main, of initializing certain fields 
automatically, conversion of the CCW list 
from real core to virtual storage 
addresses, appending of the CCW list if 
required, and initialization or modifica- 
tion of other fields within the IORCB. The 
purpose of these actions is to provide IOS 
with an input IORCB, that is, an IORCB with 
no main storage references, and no past 
action flags set (such as start I/O 
failure) . 

The need for appending a channel program 
with additional CCWs is determined in 
accordance with error retry requirements. 
The appendage will be made to the end of 
the channel program. If additional CCWs 
are added to the IORCB, the following 
fields will require incrementing or other 
modification: 

1. IORLN — IORCB length; calculate the 
new value in accordance with the numb- 
er of additional CCWs in the appended 

list. 



2. IORCL -- CCW list length; increment by 
the number of additional CCWs 
appended. 

3. IORST — Relative origin of "Start 
CCW".. Modify this field in accordance 
with the error retry procedure. 

4. IORSC — IORCB Software Command Chain 
flag set if addition to the CCW list 
requires it. 



MAGNETIC TAPE - 24 00 TAPE SERIES ERROR 
RETRY PROCEDURE : The device-dependent 
error procedure for the 2400 tape series is 
described as follows: 

Unit Check CCSW bit 38) : The routine 
checks the sense byte information to deter- 
mine the cause of the unit check condition. 
Sense byte information will be found in 
segment 0, page of virtual storage. 
Next, the routine checks the corresponding 
bit position in the IMSK field of the DCB. 

Load Point Sense Bit Only: The routine 
will set Complete With Error in the ECB, 
set on the Error flag, and move the CSW and 
the first two sense bytes from segment 0, 
page 0, to the DECB. The tape block count 
will be decremented by 1 and DEBMSK in the 
DEB will be incremented by 1. 



Load Point and/or Other Sense Bits Set: 

1. Bus Out Check (Byte 0, bit 2 ) — The 
retry will consist of repositioning 
the tape, if required, and a repeat of 
the failing CCW. if tape motion takes 
place and the failing operation is a 
forward or backward space of record or 
file the error will be deemed unrecov- 
erable. The routine will set the Per- 
manent Error indication in DCBIFL # set 
the Permanent Error flag in the DEB, 
and provide a return code of • 04*. 

2. Equipment Check (Byte 0, bit 3 ) — Bit 
7 of sense byte 3, or one or more of 
the bits of byte 4, will also be set 
to give more detail about the hardware 
failure. There is no original path 
error retry. Since data transfer and 
tape motion are indeterminate for all 
equipment checks, there will be no 
alternate path error retry. The rou- 
tine will set the Permanent Error 
indication in DCBIFL, set the Per- 
manent Error flag in the DEB, provide 
a message to the operator, and provide 
a return code of *04' in general 
register 15. 

3 . Intervention Required (Byte 0, bit 1 ) 
— If the addressed tape unit is non- 
existent, (indicated by sense byte 1, 
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bit 2 equal to zero) , the routine will 
try an alternate path. 



The routine will also perform ABEND 
processing for a control routine IORCB 
when the operation is other t.han 
rewind and unload (RUN) . If the 
operation is RUN then a return code of 
zero will cause a return to che task 
monitor* For a non-control routine 
IORCB, if the selected tape unit is in 
the end-of-tape area, the routine will 
set Request for Synad in the DECB and 
the Error flag in the DEB. It will 
also set Complete With Error in the 
ECB, move the CSW to DECCSW, move the 
first two sense bytes to DECSBO and 
DECSB1, and all eight sense bytes to 
DECASB. The routine will then set a 
return code and a message will be sent 
to the operator to demount the tape. 
If the selected tape unit is not in 
the end-of-tape area, execution of the 
CCW list will be resumed from the 
point of interruption. A message will 
be sent to the operator to ready the 
tape unit, and the routine will set a 
return code of zero after a return 
from the IOCAL routine . 

Overrun (byte 0, bit 5) — Data 
transfer will be stopped. Retries 
over the original path will consist of 
repositioning the tape and re- 
initiating the failing command. This 
error should not be associated with a 
control operation and, if such should 
be the case, the routine will request 
an abnormal termination of the task. 
If the error retries fail, the routine 
will send a message to the operator. 

Data Check (byte 0, bit 4) ~ Bits 
through 3 of byte 3 "will "be set to 
give more specific detail regarding 
the data check. 

a. Control Operation -- If the fail- 
ing operation is write tape mark 
(WTM) t then original path error 
retry will be attempted N times. 
The error retry procedure will 
consist of backspacing the tape 
one block, followed by an erase 
gap command, and then a repeat of 
the failing write tape mark opera- 
tion. If the error retries fail, 
the routine will send a message to 
the operator. 

If the failing operation is other 
than WTM, the original path error 
retry will be attempted N times by 
retrying the command which failed. 



Write Operation 
paragraph of a. 



Same as first 



c. Read Operation -- If the operation 
was a read backwards and if the 
tape is at load point, spurious 
noise was detected and the data 
check should be ignored. In this 
instance the routine will set on 
the DEB error flag r mark the ECB 
Complete With Error, and move the 
CSW into DECCSW and sense bytes 
into DECSBO and DECSBl. If this 
was an error retry IORCB, the rou- 
tine will set off the Error Reco- 
very m Progress indication and 
set a return code in general 
register 15. If this was not an 
error retry IORCB, the routine 
wall set a return code in general 
register 15. If the tape is not 
at load point, or if it is at load 
point but the operation was not a 
read backward, then a test is made 
to see if the block meets minimum 
block length requirements. 

If this is a noise block, and the 
interruption occurred on the last 
CCW, the routine will set a return 
code for Normal Completion ter- 
mination processing in general 
register 15. If more CCWs remain, 
the routine will rebuild the 
IORCB, and will resume the channel 
program from the point of inter- 
ruption. Whether the record was a 
noise record or not, the read will 
be retried N times. The error 
correction programming sequence 
consists of setting the correct 
mode, repositioning the tape, 
sending track-in-error information 
to the control unit, and then 
issuing a read or read backward 
command. An error that persists 
should cause the tape to be back- 
spaced five blocks (if five are 
available) , thus placing the tape 
past the tape cleaner. An attempt 
is again made to read the tape, 
using the procedure just described * 
This loop should be repeated until 
the error is corrected, up to a 
maximum of N reads. Should the err- 
or still persist, the associated 
block is defined as a permanent 
read error. The routine sends a 
message to the operator indicating 
an unrecoverable error. 

Data Converter Check (byte 0, bit 7) 
-- If the chaining check bit is on, 
the action in the subsection referring 
to CSW bit **7 below is performed. If 
the chaining check bit is not on, the 
routine will abnormally terminate. 

Command Reject (byte 0, bit 0) -- If 
the tape is file protected anl the 
channel command word was a write, 
write tape mark, or erase gap, the 
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DECID is set to X'W, an unrecover- 
able error indication is set, STOAD is 
requested, the error is recorded 

through the VMER macro, and return is 

made. If the tape is not file pro- 
tected* an exit is made via SY3ER. 



Chaining Check (CSW bit 47) : If the fail- 
ing operation is a read coinmand, the ori- 
ginal path error retry is attempted N 
times. The error retry consists of reposi- 
tioning the tape and reinitiating the com- 
mand that failed. If the error persists , 
the routine provides a message to the 
operator indicating * unrecoverable error®. 
The routine will also set on the "Permanent 
Error* flag, set on the * Permanent Error® 
indication , and move the channel status 
byte from the CSW to the IORCB* The rou- 
tine will send a return code of 8 04 § in 
general register 15* 



If the chaining check occurs on other 
than a read operation after N error retri- 
es , the routine: 

(1) Sets the Error and Permanent Error 
flags on* 

(2) Sets DCBIFL to Permanent Error 
condition* 

(3) Sets DECECB to Complete with Error* 

(4) Sets Synad Requested in the DECB« 
(5> Moves CSW from ISA to IORCB. 

(6) Interfaces with the VMER routine* 



Unit Exception CCSW bit 39) ; This bit is 
set to indicate a read of a tape mark, or a 

write in the end-of-tape area. If the CCW 
involved in this interruption is an erase 
gap (ERG) and there are remaining CCWs, the 
routine sets the 1OR0E flag on, rebuilds 

the IORCB , and resumes the CCW list with 
the remaining CCWs . if this interruption 
occurred on an error retry within an 
appended CCW, the routine rebuilds the 
IORCB and restarts with the original fail- 
ing CCW. 

If this was not an error retry, or if 
the interruption did not occur on an 
appended CCW f or if the CCW involved was an 
ERG with no remaining CCWs, the routine 
will process as follows? 

CD Set on the Error flag, 

C2) Set DECECB to Complete With Error. 

C3> Move the CSW to DECCSW. 



(*) Move the first two sense bytes to 

DSCBBO and DECSB1 and all eight sense 
data bytes to DBCASB. 

Incorrect Length CCSW bit 41) : If the 
failing CCW is a read operation the routine 
will determine if the record length con- 
forms to one of the following standards: 

For fixed block the record length equals 
a multiple of the block length. 

For variable length the CCW count equals 
the residual count plus LL* For an ASCII 
variable-length record the CCW count equals 

IX plus the buffer offset minus 4. 

An undefined length is automatically 
acceptable, and a * fixed standard* length 
is an automatic error* 

If acceptable, ^normal completion* is 
set and a return occurs. If in error, 
*S¥NAD request* and • complete with error 11 
are set in the DECB f • unrecoverable error* 
in the DEB, the sense bytes and CSW bytes 
are saved in the DCB f and a return occurs. 



DA Error Retry Routine CCZCRB) 

Da Error Retry processes synchronous I/O 
interruptions originating from a SAM or an 
Obtain/Retain operation on a DA device* DA 
Error Retry modifies the channel program, 
rebuilds the IORCB, and reissues the I/O 
request Csee chart CB> . 

Attributes s Privileged, reentrant, closed, 
resides in virtual storage. 

Entry Point s CZCRH1 — ■ Entered via type-1 
linkage * 

Input ; When this routine is entered, the 
channel status word and sense information 
pertinent to the I/O operation are con- 
tained in the ISA. 

Data References ; CHASDT, CHAISA t CHAJOR, 
CHADEB, CHADCB, CHADBC. 

Modules Called : 

VMSDR CCZCRY) — Virtual memory statistical 
data recording- 

VMER CCZCRX) -- Virtual memory error 
recording, 

VMA CCZCGA) — Get work area. 

SIR (CZCJS) « Select interruption request 
C handle asynchronous I/O) • 

QLE CCZCJT) « Build queue in task monitor, 

WTO CCZABQ) — Send message to operator. 
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>PATh CCEAAB) — Mark the device, control 
unit, or channel, down or OK. 



4TRCT CCEAH3) — Get task ID- 
SETAE CCEAAK) — Set up interruption queue. 

Exits: 

Normal — Return to SAN Posting with the 
return code in register 15. 



Error 



* Abnormal termination via the ABEND 
macro instruction, 

• SYSER. 



Operation : For general notes on device- 
dependent error procedures, see the SAM 
Posting and Error Retry routine, "Opera- 
tion* section, under "Device- Dependent 
Error Procedures . * 

For each error retry attempt the DA 
Error Retry routine increments the appro- 
priate error retry counter by 1, sets the 
Error Retry flag on in the IORCB, sets the 
Error flag on in the DHB and sets the Error 
Recovery in Progress indication in the DCB. 
The IORCB is rebuilt appropriately and 
executes the IOCAL SVC preparatory to re- 
execution of the channel program. A return 
code of zero is set in general register 15 
prior to returning to the calling routine. 

For each unrecoverable (permanent) error 
the routine sends a message to the operator 
indicating unrecoverable error, sets on the 
Permanent Error flag, sets the Permanent 
Error indication in DCBIFL and moves the 
channel status byte from the CSW in the ISA 
to IORCSB. When the error source is indi- 
cated by the channel status byte, this, rou- 
tine interfaces with the VMER routine, sets 
a return code of 'OV in general register 
15, and returns to the calling routine. 

When the DCBIMK corresponding bit is 
zero (that is, the user does not wish to 

have a retry for this error) , the routine 
will move the CSW from the ISA to DECCSW, 
move sense bytes and 1 from ISA to DECSBO 
and DECSB1 respectively, and set return 
code of • 0C f in general register 15. 

The following shows termination proces- 
sing to be done by the SAM calling routine 
after the direct access retry routine sets 
a return code in general register 15 other 
than zero. For a return code of zero 
(which occurs when the error recovery pro- 
cedure issued an Error Retry IORCB) the 
calling routine will exit to the task mon- 
itor without any further processing. 



Action 



Return Code in 
G.R. 15 

J T — T — T — T — _ 

Otl (08 | OC 1 10 j 1«4 



Set DECECB=X , 41 , =Com- 
plete With Error 



Set Synad Requested 
flag in the DECB 

Move CSW to DECCSW J v 

Move sense bytes and | ^ 
1 to DECSBO and DEC SB 1 

Set Error flag, 

DEBNF1, to 1 

Decrement DEBIOC by 1 
(Allowed IORCB o/s 

Count ) 

Move data from IORCB 
to user virtual stor- 
age , if required 

Device- dependent termi- \ ^| vU 
nation processing 

Normal Completion 
= , 7F' set in DECECB 

Link to VMSDR — after 
successful error retry 

Link to VMER 

Clear DEBNF1 to zero 
after successful error 
retry 

Set DCBIFL Error Re- 
covery in Progress in- 
dication 3 ^ after suc- 
cessful error retry 






I 
! 



CONTINGEOT ADDITIONAL PROCESSING: 



In addi- 



tion to that processing which occurs with 
each error retry attempt, the following 
contingencies may be encountered and the 
ensuing processing involved. 

Channel Data Check (2311, 2314, 2302) : 
Original path error retry is attempted. 
Each time an alternate path is requested, 
the channel status byte of the CSW will be 
moved from (0 f 0) to IORCSB in the IORCB to 
be used by the VMER routine* 

Unit Exception : The Error flag is set on 
and a test is made for a corresponding 

DECB . 

1. If a corresponding DECB exists, DECECB 
is set to indicate Complete With 
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Error, the CSW is moved from the ISA 
to DECCSW r and two bytes of sense 
information are moved from the ISA to 
DECSBO and DECSB1 . 

2. If a DECB does not exist and this is 
not a retry IGRCB, a return code of 
• 0C* is set in general register 15 
before exit. Otherwise f when a DECB 
does not eicist and this is a retry 
IORCB* a return code for VMSDR inter- 
face is set prior to exit* 

Chaining Check : There will be N original 
path error retry attempts consisting of 
repeating the original CCW list. 



Incorrect Length : The action taken in this 
case is contingent upon the format of the 
record being processed as indicated in 
DCBREC. The possible logical paths and 
actions performed are: 

1. Unknown - normal completion is indi- 
cated by a return code of s 08 • . 

2* Fariable - if the residual count of 
CSW is equal to zero, Complete With 
Error is set in the DECB f the SYNAD 
Requested flag is set, the Error flag 
is set in the DEB f the CSW is moved 
from (0, 0) to the DECB, and the 
return code is set to •0C t . 

If the residual count of the CSW is not 
equal to zero, a comparison is made between 
zero, arid the difference obtained by sub- 
tracting the sum of the CSW residual count 
and the f LI/ count from the CCW count. 

If the result of subtraction is 0, the 
return code is set to , 08 t ; and Normal Com- 
pletion processing will take place. If the 
result of subtraction is not 0, "Complete 
With Error* is set in the DECB f the SYNAD 
Requested flag is set, the error is indi- 
cated in the DEB, the CSW is moved from (0 # 
0) to the DEVB* and a return code of f 0C f 
is set* 

Unit Check (2311, 2314, 2302) : The number 
of retries over the original path is depen- 
dent upon the type of error which caused 
the unit check condition. Examination of 
the sense byte data will indicate the error 
cause. Prior to any diagnosis or error 
retry, the appropriate bit in the DCBIMK 
field of the DCB is tested against the 
corresponding bit set in the sense byte 
data. If the bit is off, further proces- 
sing will be that as contained above for 
DCBIMK corresponding bit equal to zero. If 
the bit is set on, diagnosis and retry con- 
tinues as follows; 

Equipment Check Cbyte 0, bit 3) — There 
is no original path error retry. The 



alternate path error retry will consist of 
repeating the original CCW list. 

No Record Found (byte 1, bit **) -- When 
the Missing Address marker (byte 1, bit 6) 
is also set, there are N original path 
error retry attempts. For a 2 311 the error 

retry procedure consists of a Restore CCW 
followed by a TIC to seek the original 
address. 

If the Missing Address Marker bit is not 
set, there are N original path error retry 
attempts. Initially this error retry pro- 
cedure consists of verification of the home 
address. This is done by comparing the 
CCHH of the home address stored in the 
IORCB against the CCHH of the search argu- 
ment. If the comparison indicates equali- 
ty, an ABEND situation is encountered. The 
routine performs termination processing by 
setting on the Error and Permanent Error 
flags, setting ABEND Requested in the DECB, 
and setting the return code to f 0c f in gen- 
eral register 15. 

If the CCHH comparison indicates an 
inequality* the error retry procedure will 
be as indicated when the Missing Address 
marker is set* 

Seek Check Cbyte 0, bit 7) — If Command 
Reject Cbyte 0, bit 0) is also set, an 
ABEND situation is encountered, and a 
return code of X s 12* is set before return. 
If Command Reject is not set, there are N 
original path error retry attempts . 

Intervention Requ ired (byte Q a bit I) ■•-• 
A message Mill be sent to the operator to 
ready the device and execution of the CCW 
list will be resumed from the point of 
interruption. , 

Bus Out Check (byte 0, bit 2) ~ The 
original path error retry attempt will con- 
sist of repeating the original CCW list. 

Data Check Cbyte 0, bit 4) -- There will 
be N original path error retry attempts 
consisting of repeating the original CCW 
list. After unsuccessful retries, if there 
is a data check in the count area 9 the rou- 
tine abnormally terminates. If there is a 
data check in the count area, and the Read 
Variable Length Records flag is set, and 
the failing CCW is the last in the CCW 
list, then termination processing will be 
in accordance with the return code in gen- 
eral register 15 set to s 04'» If the fore- 
going 'AND 8 situation does not occur the 
Error and Permanent Error flags, DEBNF1 and 
DEBNF2, are set, and an ABEND is effected. 

When error retry has been exhausted for 
data check and there is no check in the 
count area, then Overflow Incomplete Cbyte 
1, bit 7) is checked. If there is an 
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"Overflow Incomplete" condition, processing 
will be as follows: 

a. Add 1 to , HH i of seek to seek to next 
consecutive track. 

b. Set R=l in search argument, 

c. Set •CCHH' of search from f CCHH* of 
seek argument. 

d. Append CCW list ' B* to original CCW 
list. 

e. Set start CCW to 1st seek of List 'B'. 

f. Bookkeep CIORCB) IORCL and IORLN 

fields. 

g. Adjust count and data address of fail- 
ing CCW. 

h. Execute IOCAL SVC after setting flags. 

When error retry has been exhausted for 
data check and there is no data check in 
the count area, and Overflow Incomplete is 
not set then: 

1. If the Read Variable Length Records 

flag is set on: 

a. Subtract 1 from f R* field of 
search argument. 

b. Append appropriate CCWs to the 
original CCW list in order to 
ensure that the correct data area 
is being searched. 

c- Set Start CCW to first seek of the 
appended channel program. 

d. Bookkeep IORCL and IORLN fields, 

e. Execute IOCAL SVC after setting 
flags. 

2. If the Read Variable Length Records 
flag is not on; 

a. For a read set a return code of 
•04" in general register 15. 

b. Set DEBNF2 and a return code of 
S G4*' in general register 15 for a 
Write operation. 

Overrun Cbyte 0, bit 5) — There will be 
N original path error retry attempts con- 
sisting of repeating the original CCW list. 
When the retries are unsuccessful, an ABEND 
situation is encountered. 

Missing Address Markers Cbyte 1, bit 6) 
— There will be N original path error 
retry attempts consisting of repeating the 
original CCW list. 



Command Reject (byte , bit 0) — This 
is an ABEND situation. 

Track Condition Check Cbyte 0, bit 6) — 
An additional check is made on the Read RO 
Failed and Alternate Track Indicators. If 
the read RO failed, this is an ABEND 
situation. 

If the Alternate Track flag is set, the 
f CCHH 8 of the seek argument is set equal to 
the •CCHH 1 of the defective track plus one, 
and one of the following will occur, 
depending upon conditions : 

1. If the Overflow Incomplete (byte l f 
bit 7) bit is not set append CCW list 
"A* to original CCW list, set start 
CCW to first seek or "A" CCW list, 
bookkeep IORCL and IORLN, and Execute 
IOCAL SVC after setting flags. 

2. If the Overflow Incomplete bit is set 
on, set R=l in the search argument, 
set search argument ' CCHH* from seek 
argument f CCHH', append CCW list "B" 
to original CCW list, set start CCW to 
first seek of list "B", set the IORCL 
and IORLN fields of the IORCB, adjust 
the count and data address of the 
failing CCW, and execute the IOCAL SVC 
after setting flags. 

If the Track Condition Check is set and 
the Alternate Track flag is not set, the 
DEBATE and DEBETK s MBB ' are set from the 
seek argument "MBB" , the DEBATK *CCHHR S is 
set from the 'CCHHR* of the alternate 
track, the DEBETK , CCHHR i is set from the 
•CCHHR 8 of the defective track, and the 
seek argument 'CCHH* is set from the *CCHH S 
of the alternate track. If Overflow Incom- 
plete is not set, process as in 1 under 
Track Condition Check. If Overflow Incom- 
plete is set, process as in 2 under Track 
Condition Check. 

Track Overrun (byte 1, bit 1) — There 
will be no error retry. The routine will 
set a return code of "04 f in general 
register 15 and will return to the calling 
program. 

Cylinder End (byte 1, bit 2) — If the 

Overflow Incomplete bit is set, or if Read 
Variable Length Records is not set, or if 

the failing CCW is not the last in the ori- 
ginal CCW list, then the processor will set 
on the Error flag and the Permanent Err 
flag, set DECECB to Complete With Error, 
set on the DECB ABEND Required flag bit, 
and set DCBIFL to indicate Permanent Error 
condition* The CSW is moved to the DECCSW, 
sense bytes and 1 to DECSBO and DECSB1 , a 
message is provided to the operator indi- 
cating a permanent error and there is a 
return to the calling program with a return 
code of • 0C f in general register 15. 
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If Overflow Incomplete is not set and 

Read Variable Length Records is set and the 

failing CCW is the last of the CCW list, 
then the routine will set DEBHIO to all 1 
bits, set 10RRV=O t set a return code of 

'08* in general register 15 and return to 

the calling program for Normal Completion 

processing. 

File Protect Cbyte 1, bit 5) -- The com- 
mand reject bit will also be set when this 
condition is detected. There will be no 
error retry* This is an ABEND situation, 

5i ■ ^ Post ing a nd_ Er ror Retry R out in e 
( CZCMG) 

This routine records the results of an 
I/O operation from or to a unit record 
device and determines future processing. 
MSAM Posting is called by the task monitor 
as the result of a synchronous I/O inter- 
ruption following rhe execution of an I0RCB 
by the MSAM Read/Write routine, or as the 
result, of an asynchronous I/O interruption* 
such as when the operator has reset a 
jammed device. If the I/O operation was 
completed normally § MSAM Posting records it 
so that further processing may continue* 
If an error or unusual condition occurred, 
MSAM Posting records the condition and may 
determine whether to retry the operation or 
notify the operator before returning to the 
task monitor. (See Chart CO - 

Attributes : Read-only , privileged, reen- 
trant, nonrecursive- 

Entry Points : 

CZCMG1 — Primary entry point from the task 

monitor with interruptions masked off. 

Type-1 linkage. 

CZCMG2 — Entry point following an asynch- 
ronous interruption. Type-1 linkage. 

Input : Register 1 contains the address of 
the ICB« 

Data References : CHAISA f CHADCB, CHAD£B # 
CHADEC # CHASDT, CHASDA, CHAJOR, CHA1CB* 

CHADBP* 

todules Called : 

VMER CCZCRX) — Informs the operator of the 

failing task I/O component and generates 

I/O error records . 

VMSDR CCZCRY) ■ — Accumulates error statis- 
tics on task I/O devices* 

SIR (CZCJS) ™ Specify interruption 
routine. 

DIR CCZCJD) — Delete interruption routine. 

Reset CCEAAH) — Reset Device Suppression 
flag routine* 



SYSER (CEAIS) — System error processor. 

WTO or WTOA CCZABQ) -- Write mtniHttqe to 
operator on console typewriter. 



E xits : 
Normal 



Register 15 contains 00, 



Error — Register 15 contains the return 
code passed from VMER or VMSDR. 

Operation : What happens in MSAM POSTING 
depends on the type of device C reader , 
punch, or printer) on which the I/O opera- 
tion occurred, and on whether the device is 
central (located at the central installa- 
tion) or remote (located away from the 
central installation; remote job entry). 
Although the general logic in MSAM Posting 
is similar for all unit record devices, the 
sequence of operation and special consi- 
derations vary and require separate 
explanation. This description is divided 
into two parts. The first part explains 
MSAM Posting processing for central instal- 
lation devices* The second part explains 
MSAM Posting processing for remote job en- 
try devices. 



CENTRAL INSTALLATION DEVICES 

NORMAL I/O COMPLETION : On entry to MSAM 
Posting, the number of outstanding lORCBs 
is decremented by one- After falling 
through a series of abnormal condition 
tests, the Retry in Progress flag is set 
off in the DECB, the DECB is marked Normal 
Completion, the remaining DECBs are checked 
for Posting Reissue flag on (if so, the 
associated lORCBs are reissued) , and return 
is made to the task monitor. 

OTHER THAN NORMAL I/O COMPLETION : In gen- 
eral , where some abnormal condition is dis- 
covered, retry procedures are initiated* 
depending upon the condition and the 

device* If recovery is possible and the 
number of retries for a given condition has 

not been exceeded f the IORCB is reissued by 
MSAM Posting. If no recovery is possible, 
or if all recovery procedures have failed* 
the DECB is marked complete with error, and 
flags are set for unrecoverable and, if 
applicable, permanent error. A modified 
form of the CSW and the ISA sense byte are 
moved to the DECB, a message is sent to the 
operator with the WTO instruction, all 
DECBs whose Posting Reissue flags are set 
on are marked intercepted, the Posting 
Reissue flag is reset f and control is 
returned to the task monitor. 

Priority of Checking I/O Results : The 
tests in MSAM Posting to determine results 
of the I/O operation are made in the fol- 
lowing order for a card reader or card 
punch ; 
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1. No Path Available 

2. Purged I/O Operation 

3. CCWs Not Relocated (specification 
error) 

4. IORCB Intercepted 

5. Start I/O Failure 

6. CSW Status Zero 

7* Prior Error Check (on normal 
completion) 

8 . Channel Control Check 

9. interface Control Check 

10. Channel Data Check 

11. Invalid CSW Status Bits Set 

12. Unit Check - Sense Failure (invalid 
sense information) 

13. Unit Check - intervention Required 
1*4. Unit Check - Command Reject 

15. Unit Check - Bus Out Check (initial 
selection) 

16. Unit Check - Bus Out Check (data 
transfer) 

17. Unit Check - Equipment Check 

18. Unit Check - Data Check 

1**. Unit Check - Unusual Command Sequence 

20. Prior Error Check (not normal 
completion) 

21. Program Check 

22. Protection Check 

23. Unit Exception 

The priority for checking an I/O operation 
for a printer is: 

1 -12. Same as for reader and punch 

13. Unit Check - Equipment Check 

1U. Unit Check - Code Generation Storage 
Parity 

15. Unit Check - Intervention Required 

16. Unit Check - Bus Out Check (data 
transfer) 



17. 

18. 

19. 
20. 
21. 

22. 

23. 
24. 



Unit Check 
selection) 



Bus Out Check (initial 



Unit Check - Channel 9 

Unit Check - Command Reject 

Unit Check - Data Check (UCS option) 

Prior Error Check (not normal 
completion) 

Program Check 

Protection Check 

Unit Exception 



Description of Posting and Recovery 
Efforts : Posting and recovery efforts in 
the order in which they occur (based on the 
priority lists above) are described below. 

Name references appearing in parentheses 
at the end of paragraphs in the following 
descriptions correspond to block labels in 
flowchart CC and statement names (labels) 
in the listing of module CZCMG (MSA*6 
POSTING) . 

No Path Available is set because no path 
is available and may be due to setting all 
paths disabled during alternate path retry. 
The associated entry in the SDAT for the 
device will be marked "phase out" by set- 
ting SDACE. The SDA entry must be locked 
during this change. A. message is sent to 
the operator and permanent error posting is 
done (TESTLOCKK 

A Purged I/O Operation indicated by 
IORPG causes an unrecoverable error to be 
set and return is made to the task monitor. 
A permanent error will be set if purged I/O 
occurs recursively more than ten times 
(TSTPURGE-UNRERR2) . 

If the CCWs are not relocated (specifi- 
cation error) g an unrecoverable error is 
posted and a minor software. error is rec- 
orded by issuing the SYSER macro instruc- 
tion (CCWSPEC). 

IORCB Intercepted occurs when one or 
more lORCBs to be executed during an opera- 
tion failed to be executed because of an 
interruption during an IORCB being executed 

earlier in the operation, .If no prior 
unrecoverable error has been recorded and 
retry is not already in progress f the IORCB 
is reissued (INCEPTED - PRIERR) . 

Start I/O Failure indication occurs for 
busy or not operational conditions. An 
alternate path is requested by setting 
IORAJL r and a message is sent to the opera- 
tor after requesting alternate path retry. 
If successful, normal posting occurs. If 
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unsuccessful, each alternate path is tried 
once and a message is sent to the operator. 

When ail paths have been tried unsuccess- 
fully, permanent error posting occurs 
(INCEPTED) - 

A Z ero CSW should not occur anci causes 
an unrecoverable error to be posted and a 
minor software SYSER (TSTCSW) . 

Prior Error Check indicated when CSW 
status bytes equal normal completion means 
some previous data may have been lost. The 
Error Retry flag is set off and an unrecov- 
erable error is posted unless the I/O 
operation involves Form-D printing (that 
is, a dump). In that case, the operation 
is not considered unrecoverable and normal 
completion posting occurs (TSTSTAT) . 

Channel Control Check is one of four 
error conditions that is retried and then 
posted as an unrecoverable error when suc- 
cessful* This is because a record may have 
been lost or duplicated* These error con- 
ditions (channel control check* interface 
control check, invalid status or sense con- 
dition) set the error check flag, IOREC, to 
permit correct posting after retry occurs. 
If none of these error types occur after 
retry , then an unrecoverable error is post- 
ed* An exception is Form~D printing which 
is analyzed for a lower priority error or 
posted normal* After determining a channel 
control check condition exists , the flags 
lORAL and IOREC are checked to see if a 
prior error condition caused alternate path 
retry to be requested or if a prior Error 
Check condition occurred- If either flag 
is set, VMER is called to record a hard 
inboard error, the Alternate Path Retry 
flag is set f and a message is sent to the 
operator prior to reissuing the JORCB, If 
a prior error condition does not exist., the 
Error Check flag is set and the IORCB is 
reissued along the same path. A successful 
retry results in an unrecoverable error 
being posted (unless Form-D printing is 
underlay) , Unsuccessful retries result in 
one retry at each alternate path, with VMER 
being called and a message sent to the 
operator in each case (TESTCCC-ALTPATH1) . 

In terface control check occurs if there 
are channel or control unit problems* Pro- 
cessing is the same as for channel control 
check above CTEST1CC). 

Channel Data Check occurs when the chan- 
nel detects a parity error in the informa- 
tion transferred to or from main storage on 
an I/O operation. VMER is called to record 
the error on each occurrence- Processing 
is as follows; Flags IORAL and IOREC are 
checked to determine if a prior error con- 
dition caused alternate path retry to be 
requested or a prior Error Check condition 
occurred. If either flag is set, alternate 



path retry is requested, VMER is called to 
record the error, and a message sent to the 
operator. If neither flag is set, the same 
path is retried according to the threshold 
values SDTCRO, SDTPUO, or SOTPRO for the 
card reader, punch or printer respectively. 
Normal posting is done for successful 
retry. An alternate path is requested if 
the threshold value has been exceeded, A 
message is sent to the operator after requ- 
esting retry at an alternate path 
CTESTCDC-ALTPATB2) . 

Invalid CSW status Bits cause processing 
similar to that for channel control check. 
The invalid bits are 3 2 (attention) , 33 
Cstatus modifier), 34 (control unit end), 
47 (chaining check), and m (incorrect 
length) ; these bits should not be set for 
unit record devices. VMER is called to 
record the error on each occurrance; a mes- 
sage is sent to the operator after request- 
ing retry at an alternate path (TESTINVL) . 

Unit Check - Sense Failure is processed 
the same way as channel control check- A 
sense failure is caused by a sense coimiand 
failure or invalid sense information. 
Sense bits 5 and 7 should not be set for 
the card reader or card punch* Sense bit 6 
should not be set for the printer* Sense 
bits 4 and 5 may be set for the printer 
only if UCS is specified. All conditions 
can occur for either channel or control 
unit problems, VMSDR is called to record 
the error and a message is sent to the 
operator after requesting retry at an 
alternate path. Each alternate path is 
tried once (TESTUC). 

The following unit check processing is 
dependent on the type of unit record 
device , 

* For th e re ader or punch : 

Unit check - in tervention require d 
occurs when the unit is not ready due to 
any of several conditions* Cards are not 
at each station (not EOF for reader), a 
stacker is full, the hopper is empty (not 
EOF for reader) , the stop key is depressed 
the chip box is full or removed, or a card 
is jammed. A message to the operator is 
set up telling him that intervention is 
required. Asynchronous interruption proce 
duxes follow. The message previously set 
up is sent to the operator (WTO) . The Spe 
cify Interruption Routine (SIR) macro 
instruction is issued, the Error Recovery 
in Progress flag set on in the DEB, and 
control is returned to the task monitor. 
The operator performs the required action, 
correcting the condition requiring inter- 
vention or replacing the card on the equip 
ment or data check, and makes the device 
ready. The asynchronous interruption 
occurs, control is transferred to the Post 
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i nq entry jioint, <"*ZCMc;2, the virtual 
storage 1GRCB is reir.sued, the number of 
outstanding IOHCBs is incremented by one 
and return is made to the task monitor 
(INITSEL-ISINTV) - 

A Command Reject occurs when a command 
is given which the device is unaiole to 
execute. Posting is done for an unrecover- 
able error and if the DCB did not specify 
FORTRAN (formerly ASA) or machine control 
characters a minor software SYSER is rec- 
orded (TESTCREJ). 

Unit Check - Bus Out for the reader or 
punch occurs when a parity error is 
detected on a bus out during either initial 
selection or command selection. Original 
path retry will be attempted the number of 
times specified in the SDT. A flag will be 
set in the DEB to indicate error recovery 
is in progress and the Error Retry 
Attempted flag set in the IORCB. The vir- 
tual storage IORCB will be reissued and 
control returned to the task monitor. If 
all retries on one path fail, VMSDR will be 
called to record hard outboard error sta- 
tistics, a message will be written to the 
operator, and the IORCB will be reissued on 
an alternate path (BUSOUT-ALTPATH5I . 

A Unit Check - Equipment Check will 
cause retries on the same path to be 
attempted the number of times specified 
separately for reader and punch in the SDT. 
In each case, prior to returning to the 
task monitor, the Error Recovery in Pro- 
gress flag is set in the DEB, the Error 
Retry Attempted flag is set in the IORCB, a 
message is sent to the operator, and an 
interruption routine is specified with the 
SIR macro instruction. The message sent to 
the operator directs him to take appropri- 
ate corrective action on the reader or 
punch. Such action creates an asynchronous 
interruption and MSAM Posting is entered at 
CZCMG2 where the Error Retry Attempted flag 
is set in the IORCB, the virtual storage 
IORCB reissued, and the number of outstand- 
ing lORCBs incremented by one before 
returning to the task monitor. 

Where the maximum number of retries have 
been done, an alternate path is tried; a 
message is written to the operator request- 
ing an alternate path, and again MSAM Post- 
ing returns until entered as the result of 
operator action. In the event alternate 
path retry is performed, a hard outboard 
error is recorded via VMSDR for the failing 
path CALTPATH3). 

Unit Check - Data Check occurs when an 
invalid card code is detected. This can 
occur only on a read command. If the card 
is a control card, two flags are set on in 
the DEB to indicate that a control card has 
been read. If the card is not a control 



card and the retry option in' the UCH speci- 
fies no retries, the pocket opi ion i u tne 
DCB is tested. This determines whether the 
Feeder and Stacker Select command is 
changed to use the stacker specified in the 
pocket option or whether the card is 
stacked as it" no error occurred. A flag is 
set in the DEB to indicate that an invalid 
card has been read and accepted, a t lag is 
set in the virtual storage IORCB to indic- 
ate error retry attempted, and the DEB 
Error Recovery in Progress flag is set on. 
The virtual storage IORCB is reissued at 
the next feed, select stacker command with 
command chaining suppressed, the number of 
outstanding IORCBs is incremented by one, 
and control is returned to the task monitor 
(RPBIT4-TESTPOCK-RETRY2) . 



If the card is not a control card and 
the retry option in the DCB specifies an 
unlimited number of read retries, a message 
is issued (WTO) informing the operator to 
replace the erroneous card for the retry 
attempt. Asynchronous procedures are 
handled as in Intervention Required, except 
that a flag is set on in the IORCB to ind- 
icate an error retry was attempted 
(CHKCOUNT-SETASYNC) . 



Unit Check - Unusual Command Sequence is 
caused by a read following a read with no 
intervening feed- This condition is allow- 
able only if an error retry is in progress. 
Processing continues with the next CCW. If 
unusual command sequence occurs when an 
error retry is not in progress, posting for 
an unrecoverable error occurs CRPBIT6). 

A Prior Error Check indicated when sta- 
tus bytes showed other than normal comple- 
tion is treated as an unrecoverable error 
for a reader or punch CTESTEC - UNRERR2). 

If a Program Check or Protection Check 
occurs on the reader or punch, there is no 
recovery procedure. Unrecoverable error 
posting is done and, if a protection check, 
SYSER is invoked to record a minor software 
failure (TESTPGC - TESTPTC - UNRERR2 - 
MISERR4) . 

A Unit Exception on the punch should 
never occur* If it does, permanent error 
posting is done and a minor software SYSER 
recorded. A unit exception on the reader 
indicates end of file (data set) and normal 
completion posting is done. A flag is set 
on in the DEB to indicate end of file 
(TESTPTC >. 

• For the printer ; 

A check is made for invalid sense bits 
as explained above under Unit Check - Sense 
Failure (PRUNITCK) . 
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Uni t c heck - Equipment Check is pro- 
cesaed similar to equipment check proces- 
sing for the reader and punch. This unit 

check can be caused for a printer by either 

a hammer check or a buffer parity error 
(PRBIT3) • 

Unit Check - Co de Generator Parity Error 

causes original path retry to be done the 
number of times specified in the SDT. It 
occurs only if the code generator storage 
is being reloaded for a printer with the 
universal character set CUCS) feature* If 
retry over the same path is unsuccessful, 
an alternate path is requested and a mes- 
sage sent to the operator. The error is 
recorded as intermittent when successful or 
as solid when unsuccessful for a path* The 
error is processed the same for each path* 
except each alternate path is tried once 
CPRBIT5) . 

— : '^nir check - Intervention Required is 
the error, and the DCB for type is D or S 
(that is r form-sensitive), the operator 
will be sent a message to ready the print- 
er. The SIR macro instruction will be 
issued to handle the expected asynchronous 
interruption. The error recovery in pro- 
gress flag will be set on in the DEB and 
control will be returned to the task mon- 
itor* When the operator signals correction 
of the error condition by hitting the stop 
button followed by the start button, the 
asynchronous interruption will occur. 
Posting will be entered at its second entry 
point CCZCMG2) , which was specified in the 
Specify Asynchronous Entry Condition macro 
instruction ICB. The virtual storage IORCB 
will be reissued beginning with the failing 
CCW, the number of outstanding lORCBs 
incremented by one, and control returned to 
the calling program* For form type~F, a 
message is sent to the operator directing 
him to mark the error page. The fixed area 
of the IORCB is moved from the interruption 
storage area to the DEB page. The address 
of the ICB in the DEB page is stored in the 
DCB f and the V- and R-con for posting entry 
2 are stored in the ICB. The SIR macro 
instruction is issued to service the 
expected asynchronous interruption , the 
error recovery in progress flag is set on 
in the DEB, and control is returned to the 
task monitor. After the asynchronous 
interruption occurs, processing is identic- 
al to that done for error recovery on form 
type F for the printer after an equipment 
or data check CINITSEL - PRBIT1 - PTRINT - 
SETASYN2 - SETASYNC) . 

Unit Check - Bus Out is caused by a 
parity error on a command Cinitial selec- 
tion) or data (data transfer) byte. Each 
path is retried the number of times speci- 
fied in the SDT; when the maximum is 
reached, the failing path is recorded via 
VMSDR, a message is sent to the operator 



about the failure, and the IORCB is reis- 
sued along a new path CPRBIT2 - PRBOUT - 
RTRYBOUT) . 

If Unit Check - Channel 9 was sensed by 

the printer during the previous carriage 
motion and no other status or sense bits 

are set* processing continues with the next 

CCW. If FORTRAN (formerly ASA) or machine 
control characters have not been specified 
and there was a unit exception, the failing 

CCW is changed to a skip to channel 1 and 
processing continues. If any other sense 
bits are on, no special processing is done 
for the channel 9 indication CPRBIT7 - 
UEPRINT - NEXTLINE - RETRY3) . 

Unit Check - Command Reject is processed 
for the printer as explained for the reader 
and punch above CPRBITO - CMDREJ) . 

Unit Check - Data Check occurs only with 
a printer having the UCS feature when a 
code in data storage finds no match with 
any code in code generator storage. If 
SETUR had not been previously called by the 
user to load the buffer, a message is sent 
to the operator and an unrecoverable error 
is posted. Otherwise, the first time a 
data check occurs the buffer will be 
reloaded prior to the write retry. When 
the buffer has been successfully reloaded, 
the print retry counter is set to a number 
specified in the SDT and the failing CCW is 
changed to print without skipping, spacing, 
or command chaining - A flag is set in the 
IORCB to indicate error retry attempted* 
the IORCB is reissued, the number of out- 
standing lORCBs incremented by l f and con- 
trol returned to the task monitor. After 
the maximum number of retries have 
occurred , a message is sent to the operator 
indicating task ID and buffer arrangement. 
SIR macro instruction is issued to handle 
the possible asynchronous interruption from 
the operator. Posting is done for an unre- 
coverable error and control is returned to 
the task monitor. 

If the operator wishes to accept the 
error and block further data checks, he 
will depress the stop and start buttons, 
thereby causing the asynchronous interrup- 
tion. Posting invoked at its second entry 
point, CZCMG2* will proceed with the next 
line to be printed , except that the first 
CCW to be issued will be a block data com- 
mand (UNRERR-RLDBFR-RETRY4-TSTCNT-ASKOPER) • 

A Prior Error Check (not normal comple- 
tion) is treated as an unrecoverable error 
unless Form-D printing (that is, a dump) is 
in progress. If Form-D printing is in pro- 
gress, MSAM Posting assumes the user is 
willing to have the job continue; proces- 
sing continues to test for program check, 
protection check, or unit exception CTESTEC 
- UNRERR2) . 
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If a Program Check or a Protection Check 
on the printer occurs, there is no recovery 
procedure. Unrecoverable error posting is 
done and unless FORTRAN (formerly ASA) or 
machine characters were not specified on 
the program check, SYSER is invoked to 
record a minor software failure (TESTPGC - 
TESTPTC - CJNRERR2 - MISERRi*) • 

A Onit Exception on the printer indi- 
cates the end of a page has been reached 
and a skip to the next page is required. 
If FORTRAN (formerly ASA) or machine con- 
trol characters are in use (meaning the 
user handles his own skipping) , the current 
EORCB will be reissued at the next CCW. 
The number of outstanding IORCBs is incre- 
inented by one and control returned to the 
task monitor. If FORTRAN or machine con- 
trol characters are not in use, a skip to 
channel 1 command will be inserted over the 
last executed CCW, the virtual storage 
IORCB will be reissued beginning with the 
skip to channel 1 , the number of outstand- 
ing IORCBs is incremented by one and con- 
trol is returned to the task monitor 
CUEPRINT - NEXTLINE - RETRY3) . 



Unit check - time out error is recorded 
via VMSDR, permanent error is posted, 
CHKINTM and WTO are called if it is a 
•should not occur* error (IORJESN is on). 
If it is a 'should occur* error (IORJESN is 
off), then the operation is set up to be 
handled by an asynchronous interruption 
(TOCHK) . 

Unit check - intervention required 
results in the first byte of the DECB being 
set to hex 14 so that BULKIO may reinitia- 
lize the job (IRCHK). 

Unit check - lost data, data check, or 
overrun errors are recorded via VMSDR, per- 
manent error is posted, CHKINTM and WTO are 
called- If IORJESN is on, subsection 2 of 
the error counter tables is used for reco- 
rding the error. If it is off, subsection 
1 is used CDATACHK). 

Unit check - busout, equipment check, or 
command reject errors are recorded via 
VMSDR, permanent error posting is done, 
CHKINTM and WTO are called (BOCHK - 
EQUIPCBK - COMMREJ). 



If no sense bits were found on, a minor 
software SYSER is called. 



REMOTE JOB ENTRY DEVICES 

For remote job entry devices (reader or 
printer? a punch is not supported), normal 
I/O completion results in processing ident- 
ical to that for central installation 
devices plus several additional processes. 
Buffer input received from a reader is 
checked for the presence of an ETX charact- 
er? where found, it indicates end-of-data- 
set (end-of-f ile) and a flag is set. Where 
unissued IORCBs are to be reissued as the 
result of a prior unsuccessful completion, 
synchronization of ACK characters is 
assured for the reader before an IOCAL is 
issued (TESTRJE - SETENOF - REISSl - 
CHECKACKK 

In general, MSAM Posting performs only 
posting functions for remote job entry 
devices. Necessary error recovery proce- 
dures are performed by the resident super- 
visor. MSAM Posting error processing for 
both the remote reader and printer is 
explained below. 

Channel control check, interface control 
check, and channel data check errors are 
recorded via VMER, CHKINTM is called if 
intermittent errors are present, and a mes- 
sage is written via WTO to the TSS operator 
informing him of the permanent channel 
error (NORMRJE - TESTICC - TSTCDC) . 

Unit check - sense failed error is rec- 
orded via VMSDR, permanent error is posted, 
CHKINTM and WTO are called (TSTDUC) . 



Unit exception - first, intermittent 
errors are recorded using the CHKINTM sub- 
routine. Then, if receive mode, the first 
byte of the buffer is checked for an EOT. 
(An EOT will be found if the operation was 
completed in the previous buffer but there 
was no room to write the EOT 1 , or if a card 
jam occurred just as the buffer was being 
completed.) If there is an EOT, the 
DCBENOF flag is checked, and if on normal 
completion is posted. If off, it indicates 
either a card jam or the "STOP* button was 
pushed. The operation will then be set up 
to be handled by an asynchronous interrup- 
tion (SKPINTM - TSTEOF - CHKSAIN) . 

If the first byte of the buffer does not 
contain an EOT, then the data buffer being 
read at the time of the interruption is 
checked for ETX or ETB. This check will be 
made at the middle of the buffer (byte 8 3) 
if IORJEOC is on, or at the end of the 
buffer (byte 167) if IORJEOC is off. If an 
ETX, the operation has completed normally, 
DCBENOF is set on, and normal completion is 
posted. If ETB is found, either a card jam 
has occurred or the STOP button has been 
pushed. Setup will be made for an asynch- 
ronous interruption. If neither ETX or ETB 
is found, a minor software SYSER is posted 
CSETEOF - CHKSAIN - RJEMSER1) . 

For unit exception transmit mode, incor- 
rect length is checked. If off, normal 
completion is posted. If on, either a 
paper jam exists or the printer was stopped 
by pushing the stop button. In either case 
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the operation is set up for an asynchronous 
interruption (CHKFORM) . 

Incorrect length errors are recorded via 
VMER # any intermittent errors are recorded 
and a message is written to the operator 
via WTO informing him of the permanent 

error CCHKIL) . 

Control unit end, program check, chain- 
ing check f and protection check errors are 
posted as permanent errors, intermitt exits 

are recorded, and a message is written to 
the operator via WTO CCUEND - CHAINCHK) . 

Attention^ status modifier, and busy 
errors are handled the same as incorrect 
length CD9) CBUSYCHK - ATTNCHK - STAT MOD) . 

If none of the status bits are found on 
a minor software SYSER is called 
CRJEMSER2) . 



TAM Posting Routine CCZCZA) 

After the termination of a TAM Read/ 
Write initiated I/O operation, control is 
passed by the task monitor to TAM Postino 
to process this I/O interruption. TAM 
Posting analyzes the interruption data to 
determine the action to be taken. It also 
examines the input message content to 
determine the buffering technique to use 
and if user errors have occurred. When 
errors occur, both recovered and unrecover- 
able error data is recorded. CSee Chart 
CD.) 

Functions provided by TAM Posting are : 

• Posting of completed I/O actions. 

• Translation and movement of user data 
on read operations. 

• Continuation of TAM Read/Write opera- 
tions which involve multiple IORCB 
generation. 

® Posting of attention signaling during 
input or output operations while the 
terminal is transmitting or receiving. 

• Detection of errors or exceptions ter- 
minating the channel program. 

• Decoding of errors or exceptions and 
initiating possible recovery action. 

• Posting of error or exception data when 
recovery has not been requested or the 
error is nonrecoverable. 

Attributes : Reentrant, resident in virtual 
storage, closed, read-only, privileged. 

Entry Point : CZCZA1 — Entered via type-1 
linkage. 



Input : The IORCB and the ISA contain 
information relative to the condition under 
which the I/O operation was terminated. 

Data Reference : CHAISA, CHAIOR, CHADEC, 
CHATOS, CHADCB, CHADEB, CHASDA. 

Modules Called : 

GETBUF (CZCMA) — Get a buffer area. 

WRITE CCZCYK) -- TAM Read/Write, 

WTO CCZABQ — Write to operator. 

RESET CCEAAH) — Permit task to access I/O 
device. 

IOCAL (CEAAO) -- I/O call. 

VMER (CZCRX) -- Virtual memory error 
recording. 

VMSDR CCZCRY) — Virtual memory statistical 
data recording. 

SYSER CCEAIS) — System error. 

Exits : 

Normal -- Return to the task monitor. 

Error -- SYSER is called in the case of an 
undefined interruption, no SDAT entry, 
an undefined inboard error, or no sense 

data. 

Operation : TAM Posting is called by the 
supervisor as the r€?sult of an I/O com- 
pleted interruption. It saves the general 
registers and then initializes them with 
pointers to the IDA, DECB, DCB f TOS f and 
IORCB buffer and CCW list. 

TAM Posting then decodes the reason for 
the interruption of the I/O operation (see 
Figure 7). On determining that the inter- 
ruption does not reflect a normal comple- 
tion, a branch is made within TAM Posting 
to initiate the appropriate recovery proce- 
dure. If this is not possible, errors or 
exceptions are analyzed, and flags are set. 

The sequence to determine the interrup- 
tion type follows: 

• IORCB flags - The flags in the IORCB 
are checked first to determine if ther 
was a HALT I/O or a START I/O failure. 
An exception condition detected by IOS 
is indicated by setting flags in the 
IORCB. 

* Inboard failures - The inboard (chan- 
nel) type of failures are tested first 
as a group (incorrect length, program 
check, protection check, channel data 
check, interface control check, chain- 
ing check). If any one is found set, 
control is transferred to the inboard 
failure analyzer. 
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Figure 7. TAM Posting: Normal Completion and Exception Analysis Paths 



IOCAL 



• Outboard check or exception - The out- 
board failures (unit check and unit 
exception) are tested individually. If 
either is set, control is given to the 
appropriate outboard failure analyzer. 



• Normal completion - The channel end 
(CE) g device end (DE> , and program con- 
trolled interruption (PCI) bits are 
tested. The detection of any CE f DE f 
or PCI bit being set will transfer con- 
trol directly to the CCW trace list. 



Table 17. TAM Posting: Terminal Length 
Statistics 



r „_ T 

| Terminal (Standard 
| Type J Length 

(IBM 1050 | 130 

I 1 

j IBM 2741 1 130 

I 1 

(IBM 1052-7| 130 



]TTY MOD 35J 



72 



T — ..„ .___ „_-™___ 1 

Maximum Single Input 
Record Buffer 

260 

260 

260 

1UU 



• Undefined operation - If there was no 
detected error or no normal condition, 
TAM Posting identifies this I/O inter- 
ruption as an undefined operation and a 
SYSER is declared. 

The CCW trace list is then traced 
directly when normal completion was decoded 
from the interruption. TAM Posting per- 
forms this CCW trace by processing each CCW 
xn the CCW list. This CCW list was just 
executed previously by IOS and is returned 
by IOS in the IORCB area of the ISA. For 
dynamic buffering the length is obtained 
from TOS and is indicated in Table 17. 



TAM Posting uses the? logical function 
list kept in TOS associated with this IORCB 
for determining necessary processing 
requirements for each CCW. in logical 
function list contains a one byte code for 
each CCW in the channel, program. For each 
CCW and its associated logical function 
code, the IORCB buffer pointer is stepped 
to the proper buffer location and the CCW 
list pointer is stepped to the next CCW. 
TAM Posting then processes the next logical 
function until the entire list has been 
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processed. Processing then continues with 
post control* If the Data-in logical func- 
tion code is present it performs the pre- 
vious action and also branches to the Data- 
in processor. This Data-in assures that a 
user buffer area is available, and trans- 
lates and moves data to this buffer area 
when required* It is the initial Data-in 
CCW, in the CCW trace list, that determines 
the user buffer area requirements. 

The Data-in processor is entered if 
there is a Data-in logical function :.n the 
CCW list. The Data-in processor coding 
determines input buffer length, detemmines 

input buffer processing requirements , tran- 
slates input data when required f moves data 
to user buffer area, and maintains input 
data bookkeeping. 

The user may supply the necessary buffer 
area, by specifying in the TAM Read/Write 
macro instruction, the address and length 
of this area. The user may also specify, 
in other parameters in this DECB or in the 
DCB f that dynamic buffering is requested. 
(See Table 18.) 

If TAM Posting issues the GETBUF macro 
instruction to obtain dynamic buffer areas, 
the user must return these buffer areas, 
when processing of the input data is 
complete. 

The input buffer length and processing 
requirements are determined by doing a 
translate and test of the input data. The 
data in the translate and test table CZAT- 
DIT) contains only one functional charact- 
er, at present, which senses the end of the 
input data record. The ZATDIT functional 
character code is used to do a table lookup 
for the processing routine to be called. 
The data in the processing control table 
(ZATDIC) is provided for this purpose and 
contains the location of the end-of-record 
processor. This end-of-record processor 
determines if translation of the input data 
is required and translates the data to 
EBCDIC when necessary. The translation 
table address is obtained from TOS. If the 
field is zero, no translation is required. 

One error condition may be determined as 
a result of the translate and test. This 
is an input buffer overflow and exists when 
the terminal operator inputs a single reco- 
rd length greater than the specified length 
for the terminal. This condition will 
cause the Master Exception flag in the 
Posting flag field of TOS to be set, and 
the Input Buffer Overflow flag bit to be 
set in the flag field of the DECB. When 
the translation requirements are completed 
the message is checked for the end of line 
(EOL) sequence of the input record (illus- 
trated in Table 19). 



Table 18. 



DCB 



I 

1 

S 

i 

1 

I— — + — - 

Option |A=£ 
ignored | L=N 



h 



Option 
ignored 



TAM Posting; Specification of 
User Buffer 

| DECB 

|L=C 



h=n 



|A=S 
|L=S 



Comment s 

Conversational move, 
dynamic buffering 
length is twice 
standard terminal 
length. 



Dynamic buffering. 
Length is stated 
value=N. 



H 



Dynamic buffering. 
Length is stated 
value=N (from DCB). 
---__„„„___., 

Dynamic buffering 
(from DCB) • 
Length is stated 
value=N C f rom DCB) . 

Dynamic buffering 
(from DCB) . 
Length is stated 
value=N. 



„„„„„+_..«_. 

BUFTEK=DYN|L=S 

1 
L=N | 

I 

BUFTEK=DYN | L=N 

I 
Length [ 
ignored | 
H „„„„^ + „ ... 

Option |A=address 
ignored j 

|L=N 

I 

L - LENGTH 

L=S - implies length in DCB. 

Dynamic Buffering - Buffer obtained by 
POSTING and address passed to user in 
DECB. A user is therefore responsible 
for returning these dynamic buffers by 
using a FREEBUF. 



Table 19. TAM Posting: Expected EOL 
Sequence 



„„„_„„ „„ H 

Buffer address is 
indicated. 
Length is stated 
value=N. 



Terminal 



(IBM 1050 

I 

| IBM 27*41 

I 

[IBM 1052-7 

I 

fTTY MOD 35 

I CR - Carriage Return 

i 



- T — . . ._. 1 

1 Sequence ( 
|CR, B 

|CR # C 

I NONE 

}CR # L.F. , XOFPf 



B 



End of Block 



! 



|C - End of Transmission! 

i 

| L.F. - Line Feed 



It is determined that the terminal has a 
specified EOL sequence when the EOL 
sequence count in TOS is other than zero. 



fXOFF - Transmitter Off 

L 
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When a successful comparison cannot be made 
the device type code is obtained from the 
TOS and used to do a table lookup for the 
abnormal EOL routine for that device. 

The IBM 1050 and 2741 use a ccmmon 
Abnormal End of Line routine and it is 
entered whenever the ending sequence is 
other than the expected- The routine will 
determine one of four possible conditions: 

1. B--EOB character only ~~ Normal allow- 
able ending which may indicate card 
input of inter- line record formatting. 
Detection of this condition will inhi- 
bit the placing of the New Line code 
character in the data record and will 
return to the normal program flow. 

2. Last character received is C — -EOT -- 
If this character is received the Unit 
Exception flag in the Post Flag field 
in the CHATOS is tested, and if set, 
the Message Complete flag will be set 
and the return is to normal Data-in 
processing flow. If the Unit Excep- 
tion flag is not set, the Attention on 
Read and Master Exception flag are set 
in the Posting flag field of the CHA- 
TOS and the Attention flag bit in the 
Pre-Post Data field in the CHATOS is 
set. Control is then returned to the 
normal Data-in processor flow. 

3. Neither B nor C -- The Master Excep- 
tion flag in the Posting flag field of 
CHATOS is tested. If on, control is 
returned to the Input Data processor 
to allow the record in error to be 
moved to the user buffer area. 

^« if the Master Exception flag is not 
set, an undefined system error has 
occurred and control is given to the 
undefined error routine. Should the 
record length prove to be greater than 
the user the user buffer remaining 
count field, that portion of the reco- 
rd equal to the user buffer remaining 
count is moved to the user buffer 
areas, the User Buffer Overflow flag 
in the flag field of the DECB is set, 
and the master exception flag bit in 
the posting flag field of the TOS is 
set. Normal processing continues with 
control being returned to the CCW 
trace list as if no user buffer over- 
flow had occurred. 

If the EOL sequence comparison is suc- 
cessful the first character of the EOL 
sequence is overlaid with an EBCDIC new 
line CNL> character and the record length 
is adjusted to include the text plus the NL 
character* This record length is then com- 
pared to the user buffer remaining count 
field of TOS. If it is equal or low, the 
lecord is moved from the input buffer to 



the user buffer area. The user buffer 
pointer, user buffer remaining count, and 
input character count fields in the TOS are 
updated. Control is then returned to the 
CCW trace list. 



The CCW trace list coding continues for 
each logical function byte until the entire 
CCW list has been processed. When the last 
CCW is processed, we continue processing 
with the proper post control coding as 
determined by the option type-code 
reference in the post control table. 

The functions of the post control rou- 
tine coding are to determine the proper 
posting and control for: 

• Read operation entry 

• Write operation entry 

• Write with response entry 

• Control order entry 

If a read request is complete within 
this IORCB, the area and length are moved 
to the DECB and common DECB posting con- 
tinues. If the read is not complete, TAM 
Read/Write is called. 

If a write is complete within this 
IORCB, common DECB posting continues. If 
the write is not complete, TAM Read/Write 
is entered as a subroutine. 

If the write with response is complete 
within this IORCB, the data in the buffer 
bit in the Posting flag field of TOS is 
tested. If set, the Message Complete flag 
is set in the Post flag field and control 
is transferred to post control read. If 
the data in buffer bit is not set, enter 
TAM Read/Write is entered as a subroutine. 

If write with response is not complete, 
TAM Read/Write is entered as a subroutine. 

If a control order entry, common DECB 
posting continues. Common DECB posting 
ends post control by making an initial test 
of the Master Exception flag in the Posting 

flag field of TOS. If set, the ECB field 
of DECB is posted complete with error and 
the synad request is set in the? DECB flag 
field. If the Master Exception flag is not 
set, the ECB field of DECB is posted com- 
plete without error and the prepost data 
field is moved to the DECS flag field. 

Common DECB posting then moves CSW and 
sense data from ISA to DECB. If the Master 
Exception flag is set, TAM Posting does not 
allow entering TAM Read/Write as a subrou- 
tine but continues with common DECB 
posting. 



Section *4 ; Posting and Check 6 3 



After completing common DECB posting the 
housekeeping completion routine coding is 
executed. The housekeeping function 

includes : 

• Recording unrecoverable error data 

• Recording recovered error data 

• Clearing error counters and error data 

fields 

• Preparing line on abnormal end and 
return 

• Issuing status of IORCB and return 

« Setting up normal return to task 
monitor. 

Note that TAM Posting does not issue an 
ABEND- On determining any exception or 
error condition, the appropriate informa- 
tion is posted in the DECB and at the prop- 
er time a return is made to Task Monitor. 

Only if TAM Posting cannot determine a 
path to follow will it issue a SYSER. 

TAM Posting provides exception analysis 
error decoding and recovery actions. The 
processing of all exceptions except atten- 
tion interruptions posts ail data to the 
user, whenever error recovery is not indi- 
cated or possible. The following flags may 
be set in TCS to communicate unrecoverable 
termination status to the user via the DECB: 

• Unit Exception flag - set when a func- 
tion is terminated by unit exception, 

• Master Exception flag - set whenever an 
exception interruption has terminated 
the action* 

• Abort flag - set whenever maximum error 
recovery attempts have been 
unsuccessful, 

• Attention flag - set whenever attention 
signalling is detected during a read 
type operation. 

• Recovery in Progress flag - set whenev- 
er an error recovery action is 
initiated. 

An example of Start I/O (SIO) failure 
follows. The SIO Failure flag in the IORCB 
is interrogated by the Define Interruption 
routine. If the flag is found to be on, 
transfer is made to the SIO-HIO failure 
processor. 

The status in the CSW is then interro- 
gated to see if a unit check or unit excep- 
tion has occurred. If either bit is on, 
control is turned over to the proper pro- 



cessor. If neither bit is on, a message xs 
sent to the system operator informing him 
of the Start I/O failure and the associated 

symbolic- device. 

The ABEND Required and SYNAD Requested 
ilags are set in the flaq bytes of the 

DECB. The ECB field of the DECB is set to 

indicate "complete with error". A oranch 
to the Housekeep and Return subroutine 
occurs . 

The two types of outboard failures are 
unit check and unit exception. Each has 
its own control routine coding whose pur- 
pose is to determine the recovery action to 
be initiated. Each of the recovery rou- 
tines is coded to operate for unique combi- 
nations of conditions. 

As an example of error recovery on unit 
check, TAM Posting starts with the inter- 
rupted CCW obtained through the data pro- 
vided in the ISA and the IORCB located in 
the ISA. The sense byte bits in the ISA 
are then tested in a predetermined 
priority. 

When a test is found to be positive, a 
counter located in TOS which represents 
that sense condition is stepped and tested 
for a maximum count. Refer to Table 20 for 
CSW status and sense data typical f maximum 
exception retry 9 counts. 



When any sens 
is stepped to ma 
set to indicate 
the failures are 
branches to cone 
is a recoverable 
recording saves 
TOS. After this 
Director routine 
access the Unit 
be initiated as 
tion conditions 



e condition retry counter 
ximum, the Abort flag is 
an unrecoverable condition, 

recorded, and TAM Posting 
iusion housekeeping. If it 

condition the internal 
pertinent error data in 

recording, the Unit Check 

coding is entered, to 
Check Recovery routine to 
determined by the interrup- 



The Reinitialize IORCB subroutine is 
provided to be used by ail unit check 
action routines. Prior to entering, all 
altering of the channel program and buffer 
data is completed. This routine initia- 
lizes all relative addresses in the IORCB , 
sets the necessary flags, and issues the 
10CAL macro instruction. TAM Posting then 
sets up for a return to task monitor. 

The following describes typical unit 
check recovery routine coding provided; 

Retry Full IORCB on System Error : This 
action is used where the channel program 
has been terminated in such a way as to 
require a retry of the full program or 
posting of a system error which is unrecov- 
erable. The routine will first test the 
Abort flag in TOS, If set, it will set a 
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Table 20. TAM Posting: CSW Status and 
Sense Data Typical Maximum 
Exception Retry Counts 
(Extracted from CHASDT> 
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System Error and ABEND Requested flag in 
the DECB and enter the CCW trace list rou- 
tine. If the Abort flag is not set, the 
routine will set the Retry in Progress flag 
in TOS. The Reinitialize IORCB routine is 
then entered. 

System Error Retry from Interrupted CCW : 
This action is used whenever a system error 
has occurred and it is necessary to restart 
the program from the interrupted CCW. The 
Abort flag in TOS is tested. If set, the 
routine will set an error condition in the 
DECB and enter the CCW Trace List routine. 
If abort is not set, the Retry in Progress 
flag will be set. The relative location of 
the interrupted CCW is saved and the Rein- 
itialize IORCB routine is entered. 

Record Only ; , This action is used when an 
error has occurred which will not effect 
channel program operation, but must be rec- 
orded as a system history. It also may be 
used when the terminal is not equipped with 
error correction. A branch occurs to the 
CCW Trace List routine. 

Unit exception, for example, can be 
caused by a negative response from the 
1050 , either during addressing or polling. 



IOREQ Posting Routine (CZCSE) 

After a system interruption which occurs 
at the completion of an IOREQ initiated I/O 
operation, control is passed by the Task 
Monitor to IOREQ Posting to process this 
I/O interruption. The address ot IOREQ 
Posting is specified by the posting address 
constants in the IORCB. 

IOREQ Fosting analyzes the interruption 
data to determine the action to be taken. 
It then posts the normal or abnormal com- 
pletion code in the DECB, allowing the 
Check routine to later take action based on 
these codes, IOREQ Posting is executed in 
privileged mode, with all other task inter- 
ruptions masked off. CSee Chart CE. ) 



Attributes : Reentrant, resident in virtual 
storage, closed, nonrecursive, read-only, 

privileged. 



Entry Point : CZCSE1 -- Entered via type-1 
linkage. 

Input : None. Information relative to the 
conditions under which the I/O operation 
was completed is in the IORCB and the ISA. 

Data References ; CHAISA, CHADEC, CHADEB, 
CEADCB, CHAIOR. 

Module Called ; Reset (CEAAH) — Resets 
error flag so that task can access I/O 

device. 

Exits : 



Normal -- Return to calling program. 

Error — ABEND macro instruction. 

Operation : IOREQ Posting initially saves 
the general registers. A check is made to 
verify that the IORCB has been executed 

Cthat is, the channel program has been 

attempted) . 

If the IORCB was not executed, a check 
of the Error flag for the corresponding DEB 
C pointed to by the IORCB) is made. If the 
error flag is set, an intercepted condition- 
is set in the ECB (pointed to by the IORCB) 
of the DECB. The allowed IORCB count field 
in the DEB is decremented by 1 an a return 
to task monitor occurs. If the error flag 
is not set, an exit to ABEND occurs. 

If the IORCB was executed, the CSW is 
moved to the DECB f the ISA sense informa- 
tion is moved to the DECB, the allowed 
IORCB count in the DEB is decremented by 1, 
and the input data in the IORCB data buffer 
area, if buffering is used, is moved to the 
data area in the user virtual storage 
pointed to by the DECB. 
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If START I/O failed f Complete with 
Error* is posted, DECBSF is set to show SIO 
failure, SYNAD is requested, and the IORCB 
count decremented. The return code is set 
to zero and a return to the task monitor is 
effected. 

The CSW bits are examined and, depending 
on their settinq, normal or error comple- 
tion is posted. If the CSW=0, ABEND is 
requested and error and permanent error 
flags set in the* DEB. IOREQ Posting does 
not perforin any error recovery. 

For normal completion , "normal comple- 
tion" is posted in the ECB of DECB, and a 
return to the task monitor occurs. 

For abnormal completion, "complete with 
error" is posted in the ECB of DECB, a 
request is set for SYNAD in DECB, the error 
flag is set in DEB, and a return to the 
task monitor occurs* 



Check Routine (CZCRC) 

The Check routine is entered as the 
result of the CHECK macro instruction that 
a user issues to ensure the completion of a 
previous READ or WRITE macro instruction. 
To determine completion or other results. 
Check examines the DECB. SAM Posting and 
Error Retry will have posted information in 
the DECB if the 1/0 operation is complete. 
If not complete , Check awaits completion. 
On completion (successful or otherwise) # 
normal return, an ABEND* or set-up for en- 
try to a user's SYNAD routine occurs, 
depending on switches set by SAM Posting 
and Error Retry. Check also calls SAM 
Mainline EOV for necessary end-of -volume 
processing. If end of data set is encoun- 
tered, Check sets up entry to a user's 
EODAD routine before returning to the 
caller. 

Attributes : Reentrant, resident in virtual 
storage, closed, privileged, nonrecursive. 

Entry Point : CZCRCS -- Entered via type-lM 
or type- 2 linkage. 

Input s Register 1 contains the address of 
the DECB to be checked. 

Data References ; CHAD EC, CHADEB, CHASDA, 

CHADCB. 

Modules Called : 

SAM Mainline EOV (CZCXE) — SAM EOV main- 
line processing. 

SAM Read/Write CCZCRA) — SAM Read/Write. 

AWAIT (CEAP7) — Await an interruption. 

TWAIT CCEARO) -- Terminal I/O wait. 



Exits: 

Normal -- Returns to the calling program 
with zero in register 15. 

Other conditions -- 

* If a SYNAD condition, returns with: 

Register - DECB address 
Register 1 - 8 -hit SYNAD cod*- 
Register IS - Address ot parameter 

list containing user's SYNAD V-con 
and R-con addresses. 

* It an EODAD (end of data set) condi- 
tion, returns with: 

Register 1 - DCB address 
Register 15 - Address of parameter 

list containing user's EODAD V-con 

and R-con addresses. 

* ABEND occurs if EODAD or SYNAD exits 
needed but not provided. Reguested by 
SAM Posting and Error Retry. I/O 
requests checked out of sequence. 

Operation : If the In-Use flag in the DECB 
is not on. Check has been entered to check 
a DECB for which no I/O is outstanding. 
Therefore, control is immediately returned 
to the calling routine . 

When the DECB is in use but the I/O 
operation is not complete, the AWAIT macro 
instruction is issued to wait for the 

expected I/O event to complete. 

When the I/O event has occurred^ the 
DECB is checked for errors. The task will 
be abnormally terminated when the SYNAD or 
EODAD exit is to be given control and it is 
not supplied. 

Note ; When an intercepted DECB is checked 
and it has an end of volume request posted , 
in it, end-of-voiume processing is per- 
formed as explained below. However, if the 
intercepted DECB has no end-of -volume requ- 
est this means that the I/O associated with 
the DECB was never attempted. Therefore, 
Check links to the Read/Write routine to 
reissue the I/O request. Check waits until 
this request is complete before doing any 
other processing. 

If complete with errors is posted, and 
if there is a unit check caused by reading 
backwards into a load point, the end of 
volume processing is performed as explained 
below. 

If the DECB is marked complete with 
errors, and there was no read backward into 
load point, this means that an I/O error 
has occurred, and the system retry proce- 
dures cannot correct it. The Check routine 
first tests the ABEND bit C in the DECB), if 
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the data sot. is sequentially organized. I! 
on, this moans that the error is eat as- 
trophic, and the task eannot continue. 

ABEND is then called. If the ABEND bit is 
off, then the SYNAD request flag (in DECB) 
is tested, and the user's SYNAD exit is 
entered. If SYNAD is not on, a normal 

return is given to the user. 

If the data set is not sequentially 

organized, the Check routine proceeds as 
described above for the case in which the 
ABEND bit is found off. 

End~-of -Volume Processing : Check calls the 



Mainline EOV routi 
end of volume proc 
switching if neces 
returns to Check, 
corresponded to en 
EODAD exit is set 
the end of volume 



ne which performs various 

esses and will do volume 

sary. When control 

if the end of volume 

d of data set, the user's 

up (if supplied). When 

condition does not corre- 



spond to end ot data set, the read request 
DECB which caused tin* KOV request is. 
restarted. Should it be a write request 
DECB which causes the EOV condition, a 
normal return is made to the calling rou- 
tine with the DECB marked "Complete, No 
Errors" . 



Note that, when conditions arise which 
require a branch to SYNAD or EODAD, the 
Check routine only sets a pointer to the 
R-con and V~con of that routine in register 
15, and returns to the calling program. 
The point returned to will be within the 
expansion of the CHECK macro instruction. 
If general register 15 is zero, the next 
sequential instruction after the expansion 
should be given control,. If non-zero, the 
succeeding instructions of the expansion 
must set up a type-1 linkage with the supp- 
lied R- and V-type address constants. 



Section 4: Posting and Check 67 



SECTION 5: 



CLOSE 



CLOSE PROCESSING 

The following routines describe the 
CLOSE processors for SAM r MSAM, TKM f and 
IOR, as well as Close Common and MSAM 

Finish. 

Close Common Routine CCZCLB) 

The Close Common routine will logically 
disconnect the data set from the problem 
program, close the data control block , and 
relinquish main storage- It then branches 
to the appropriate access dependent close 
routine to complete the closing. CSee 
Chart DA. ) 

Attributes : Reentrant, resident in virtual 
storage, closed* read-only, privileged rou- 
tine, public. 

Entry Point : CZCLBC -- Entered by type-1 
or type- 2 linkage. 

Input : Register 1 contains the address of 
the CHAGSM table. The CHAGSM table is 
generated by the expansion of the CLOSE 
macro instruction and consists of one 
double word entry for each DCB (and its 
associated data set) to be closed . 

Data References : CHAGSM , CHADCB, CHATDT, 
CHADEB, CHADHD." 

Modules Called : 

SAM Close CCZCWC) -- SAM close. 

TAM Close CCZCYG) -- TAM close. 

MSAM Close CCZCMI) — MSAM close. 

IOR Close CCZCSD) — IOR close, 

VAM Close CCZCOB) — VAM close. 

VMA CCZCGA) - Free virtual storage. 

Exits : 

Normal — Return to the calling program* 

Error - - ABEND macro instruction. 

Operation : This routine performs close 
processing only if the DCB to be closed is 
open. if the close is temporary, the numb- 
er of times the data set has been open is 

not decremented as is the case in a normal 
close. 

Close Common then transfers control to 
the appropriate access dependent close rou- 
tine. When the access dependent close rou- 



tine returns, all storage assignee! to the 
DCB is released via FREEMAIN, unless the 
close is temporary in which case the 
assigned storage is not released. The DCB 
is restored to its pre-opeo condition. If 
this is not the last DCB to be closed, 
CHAGSM points to the next DCB to be 
processed. 



SAM Close Routine CCZCWC) 

Called by Close Common, SAM Close posi- 
tions the data set volume, releases storage 
allocated for the DEB f disconnects the DEB 
from the chain of DEBs # and returns unused 
DA extents to external storage (Chart DB> . 



Attributes : Reentrant f resides in virtual 
storage, closed* read-only, privileged. 

Entry Point : CZCWd - Entered by type-1 
linkage* 

Input ; Register 1 contains the address of 
the DCB. The SAM communication block 
CCHASCB) is defined in the PSECT of SAM 
close and contains three temporary control 
blocks - DCB f DEB* and DEC - which are used 
during the closing process to perform label 
processing. 

Data References : CHASCB, CHADCB, CBADEB, 
CHATDT, CHASDA f CHADEC. 

Modules Called : 

Tape Positioning CCZCWP) — Tape 
positioning. 

User Prompter CCZCTJ) -- Communicate with 
user. 

VOLCVT CCZCWV) — ■ Volume address convert, 

VMA CCZCGA) — Free virtual storage. 

GIVBKS CCZCEG) -- Release unused SAM 
external storage. 

Control CCZCRB) - — Magnetic tape 
positioning. 

Mainline EOV CCZCXE) — SAM mainline EOV 
processor. 

SETDSCB (CZCXS) — Set DSCB . 

QSAM CCZCSA) — To handle end- of -volume 
condition. 

AWAIT CCEAP7) — Await an interruption. 
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Exits : 

Normal -- Return to calling routine. 

Error — Via ABEND. 

Operation : If the device indicated in the 
DCB is direct access, the T-Close flaq is 
turned off. DA data sets may not be tem- 
porarily closed. 

The SAM control block (CHASCB) is 
initialized by zeroing out the variable 
portion, storing pointers to the DCB, DEB* 
and JFCB into it, and initializing the tem- 
porary DCB and DEB, 

The QCLOSE subroutine is bypassed if 
neither GET nor PUT is indicated in the 
DCB. If the data set being closed has been 
processed by QSAM, QCLOSE, an in-line sec- 
tion of SAM Close, is entered to perform 
functions unique to the closing of a QSAM 
data set. Control is given to the TREOV 
section of QSAM, which checks for outstand- 
ing read requests and flushes any which 
exist, or writes out any buffer which has 
oeen partially or completely filled, but 
not yet written out. (See the QSAM section 
of this publication for a description of 
TREOV.) A FREEMAIN macro instruction is 
next issued to release the storage obtained 
for the work area and buffers by QOPEN. At 
this point, QCLOSE processing is complete 
and normal processing of SAM Close 
continues. 

If the device is a magnetic tape drive, 
the common portion of the input DEB is 
copied into the common portion of the tem- 
porary DEB, and a pointer to the temporary 
DCB is stored into the temporary DEB. 
Fields in the temporary DCB are set so it 
may be used for label processing. 

SAM Close uses the AWAIT macro instruc- 
tion to make sure that all user I/O is com- 
plete before the data set f s close proces- 
sing is continued. Incomplete input opera- 
tions will be purged by SAM Close. 

Unused extents are released, via GIVBKS, 
if the following three conditions are met: 

a. device is direct access 

b. at least one full track is unused 

c. release of unused extents is specified 
in the JFCB. 

The Mainline EOV routine is then entered 
to complete end-of -volume processing if the 
last I/O operation was a write. When con- 
trol is returned to SAM Close, and if the 
device is a magnetic tape drive, the tape 
volume is positioned as specified in the 
close options by use of the Control 
routine. 



MSAM Finish Routine (CZCMH) 

MSAM Finish is used to complete proces- 
sing for a data group mounted on a unit 
record device. MSAM Finish can also be 
used to signal the end of the current data 
group without closing and reopening the DCB 
for the next data group. (Chart DC. ) 



Attributes : Privileged, reentrant, read- 
only, public, system, nonrecursive. 



Entry Points : 

CZCMH1 -- Primary entry point via type-1 or 
type-2 linkage. 

CZCMH2 — Asynchronous interruption entry 
point via type-1 linkage. 

CZCMH3 — Synchronous interruption entry 
point via type-1 linkage. 

Input : 

For entry at CZCMH1 , register 1 contains 
the address of the DCB. 

For entry at CZCMB2, register 1 contains 
the address of the ICB. 

For entry at CZCMH3, the ISA contains the 
IORCB. 

Data References : CHADCB, CHADEB, CHADEC, 
CHAIOR, CHAISA, CBADBP. 

Modules Called : 

WTO (CZABQ) — Write message to operator. 

SIR CCZCJS) — Activate an interruption 
routine. 

DIR CCZCJD) — Delete an active interrup- 
tion routine. 

Reset (CEAAH) — Reenable a device after 
I/O error. 

Exits : 

Normal — For CZCMH1 return, register 15 

contains one of the following return 

codes: 

'00' Completed successfully. 
04' Incomplete. 



I All « 



•08 f Complete with I/O error; if PUT, 

register 1 points to failing reco- 
rd, register points to user 
DECB. 

For CZCMH2 and CZCMH3 return, register 
15 contains zero. 

Error — Abnormal termination via ABEND 
macro. 



Section 5: Close 69 



UF>orat ion: In order to avoid an automatic 
wait in MSAM Close, the FINISH macro should 
be issued and subsequently reissued by the 
user until its return code indicates com- 
pletion. When the FINISH macro is issued 
by the user or by the MSAM Close, CZCMH1 is 
entered. Following an asynchronous inter- 
ruption (caused by operator response to a 
message) , CZCMH2 is entered; CZCMH3 is 
entered after a synchronous interruption 
(caused by completion of the card-read~and- 
stack operation) . 

The user can stop Finish processing by 
setting off the Finish in Progress bit in 

his DCB and calling Finish for the final 
time. This will cause any activated inter- 
ruption routine to be deleted before a 
return code indicating "complete" is given 
to the user. 

The user may also prevent the issuing of 
a data-group-end message by turning on the 
Inhibit Message bit in his DCB. This will 
cause Finish to go directly to its comple- 
tion routine at points where it would 
otherwise issue a message and wait for 
response. 

Primary Entry Point (CZCMH1) Processing : 
If the DCB or DEB are not valid, the task 
is terminated via ABEND* 

When the input is complete without 

error, the message-defining loop is 
entered. (See DCBRCX=30, below.) If the 
input is incomplete, control returns to the 
user with general register 15 indicating 
"incomplete". If the input is complete 
with error, the completion routine (see 
DCBRCX=80 below) is entered. 

When Finish is first entered on output, 
and an error was recorded by a user-issued 
PUT, no attempt will be made to flush the 
buffer. Otherwise, if no error occurred, 
the device type determines the line of 
processing. 

For a printer, a PUT is issued to write 
the last buffer page. If the PUT is not 

yet complete, the return code is set to 
"incomplete 19 and the routine returns to the 
caller. If the PUT is complete but an 
error on a Finish-issued PUT is indicated, 
the user will be provided with error point- 
ers if this has not already been done 
(error recovery will be attempted if the 
error indicator is set off) , and control 
returns to the caller with the Finish- Just- 
Issued flag on, the Finish-in-Progress flag 
off, and a return code indicating "complete 
with error" in general register 15. 

Otherwise, the message "Remove output 
from printer XXXX, then ready printer" or 
"Remove output from punch XXXX, then ready 
punch" is sent and the routine awaits 



operator response. However, if the combine 
option is indicated, an IORCB for a card to 
be read and stacked in pocket 3 is built 
and executed before this message is issued. 

For a punch, a blank record is con- 
structed and PUT in order to force the last 
card into the stacker. If this punching is 
incomplete, control returns to the user 
with general register 15 indicating "incom- 
plete". If the punching is complete with 
error, another PUT is issued to obtain 
error pointers for the user if this has not 
already been done (error recovery will be 
attempted if the error indicator is set 
off) and control returns to the caller with 
the Finish-Just-Issued flag on, the Finish- 
in-Progress flag off, and a return code 
indicating "incomplete with error" in gen- 
eral register 15. If no error occurred in 
the punching, processing continues, as with 
the printer, at the PUT for flushing the 
last buffer. 

For subsequent entries to Finish, the 
path taken depends on the value of DCBRCX 
as set by the previous FINISH. 

DCBRCX- 30 : Completion of input is being 
awaited. If the input operation is not yet 
complete, the routine returns to the caller 
with the return code indicating "incom- 
plete". If the input operation is complete 
with error, the completion routine (see 
DCBRCX=80 below) is entered. If the input 
operation is complete without error proces- 
sing continues at the message-defining 
loop. If any of the DECBs are marked com- 
plete with no errors and a unit check is 
indicated, the message "Remove output from 
reader XXXX, then ready reader" is sent and 
operator response is awaited. If a unit 
exception is indicated, the message "Remove 
output from reader XXXX" is sent and Finish 
enters its completion routine. If there 
are no such DECBs, the message sent will 
instead be "Remove input/output from reader 
XXXX, then ready reader." 

DCBRCX=A0 : Finish is awaiting comple- 
tion of the PUT. Processing continues as 
if Finish had just issued its PUT to write 
the last buffer page. 

DCBRCX=6Q : Awaiting an asynchronous 
interruption (operator response) - The 
interruption has still not occurred, so the 
return code is again set to indicate 
"incomplete" and the routine returns to the 
caller. (Not applicable to RJE.) 

DCBRCX=80 : End of wait for the asynch- 
ronous interruption. This condition is 
caused by the occurrence of the interrup- 
tion or by the user's turning off the 
FINISH-in-Progress bit before the interrup- 
tion was received. The completion routine 
is entered, the FINISH- Just-Issued flag is 
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set, the FINISH-in-Progress flag is turned 
off, the appropriate return code indicating 
"complete" is set in general register 15, 
and the routine returns to the caller, 
(Not applicable to RJE.) 

DCBRCX=50 : A wait for a card to be 
stacked in pocket 3 when the device is a 
punch and the combine option is indicated. 
If there are any outstanding IORCBs, the 
card-read-and-stack operation is not yet 
complete so the R15 return code is set to 
"incomplete" and the routine returns to the 
caller. Otherwise, if no errors were rec- 
orded on the card- read- and-stack operation, 
the message "Remove output from punch XXXX, 
then ready punch" is sent and operator 
response is awaited. If an error was rec- 
orded, the message sent instead will be 
"Feed card from reader YYYY, stack in poc- 
ket 3, remove output from punch XXXX, then 
ready punch." (Not applicable to RJE.) 

Asynchronous Interruption Entry Point 
(C2CMH2) Processing ; This interruption is 
caused by the operator changing the device 
state from "not ready" to "ready", the 
response required following the issuing of 
a message. (This routine is not entered 
# ring an RJE task.) 

The DCBRCX field is set to indicate that 
the interruption has occurred. The DIR 
macro is used to delete the interruption 
routine and control is passed to the cal- 
ling routine with a return code of zero in 
general register 15. 

Synchronous Interruption Entry Point 
(CZCMH3) Processing : This interruption is 
caused by the completion of a read, feed 
and stack in pocket 3 operation when the 
combine option is indicated. (This routine 
is not entered during an RJE task.) 

Errors occurring during the I/O activity 
may result in limited retry, depending upon 
the type of error. Any final error is rec- 
orded in the DEB. 

Except when a retry is in progress, the 
number of outstanding lORCBs is reduced to 
zero and then, in all cases, a return code 
of zero is set in general register 15, and 
the routine returns to the task monitor. 



MSAM Close Routine (CZCMI) 

MSAM Close calls Finish to complete out- 
put if necessary, to attempt recovery from 
an error on a previous PUT, or to indicate 
end of data group to the operator. MSAM 
Close frees pages of virtual storage 
obtained by MSAM Open. (Chart DD. ) 

Attributes ; Privileged, reentrant, read- 
only, public, system, nonrecursive. 



Entry Point : CZCMI1 -- Entered from Common 
Close via type-1 linkage. 

Input : Register 1 contains the address of 
the DCB. 

Data References : CHADCB, CHADEB, CHAD EC , 
CHATDT, CHASDA, CHAICB, CHADBP. 

Modules Called : 

MSAM Finish (CZCMH) — Complete output and 
indicate end of data group. 

DIR (CZCJD) — Delete an active interrup- 
tion routine. 

FREEMAIN (CZCGA) — Release virtual 
storage. 

INTINQ (CZCJI) — Interruption inquiry. 

AWAIT (CEAP7) — Await an interruption. 

RJELC (via SVC 232) — Disconnect RJE line 
control . 

Exits : 

Normal — Return to caller. 

Error — ABEND macro used for abnormal 
termination. 

Operation : If the DEB is invalid, MSAM 
Close abnormally terminates. 

Finish is called to assure that I/O has 
been completed. If it has not, the routine 
goes into the wait state (using AWAIT) 
until the I/O is complete. FINISH will 
then be reissued. This process will be 
repeated until all DECBs have been checked 
for I/O completion. If Finish is awaiting 
an asynchronous interruption the INTINQ 
macro will be issued. if Finish is in the 
process of stacking a blank card, Close 
will wait until that operation is complete. 
The interruption will then be dispatched 
and FINISH will be reissued until a return 
code is received indicating that the opera- 
tion is complete. In an RJE task, the 
INTINQ macro will not be issued (Finish 
do€?s not field an asynchronous interruption 
during an RJE task) and the test for a 
blank card being stacked is bypassed. If 
an unrecoverable error occurred on a PUT, 
FINISH is reissued in order to attempt 
recovery before informing the user of the 
error. 

The SDAT malfunction flag is set on if a 
permanent error is indicated- The DEB 
pointer in the JFCB is removed, and the DIR 
macro instruction is used to delete any 
active interruption routine. The DIR is 
bypassed in an RJE task (BULKIO specifies 
and deletes interruption routines for RJE) - 
RJE line control will be disconnected if 
the device is a remote printer and the 
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installation operator will be notified at 

his console via a WTO macro. 

If the DEB indicates user read-write 

protection class, two FREEMAIN macro 
instructions are issued to free the two 
noncontiguous groups of virtual storage 

pages obtained by MSAM Open- If user-read- 
only or user-inaccessible protection is 
indicated, a single FREEMAIN is issued to 
free the contiguous pages of virtual 

storage obtained by MSAJM Open. 

The DEB pointer in the DCB is removed, 
and control returns to Close Common* 

TAM close Routine (CZCtfC? 

TAM Close is called by Close Common if a 
user desires to close a TAM DCB, because of 
ABEND requirements for a task to be closed, 
or as a result of a LOGOFF command. 

In continuing the close processing from 
Close Common, TAM Close is called to per- 
form additonal closing functions unique to 

TAM terminals. This includes freeing the 
control blocks and buffer areas obtained 
during TAM Open and performing the disable/ 
enable function at logoff time. TAM Close 
then returns to Close Common except when an 
abnormal end is required in which case it 
goes to ABEND or SYSER. (See Chart DE. ) 

Attributes : Reentrant, resident in virtual 
storage f closed, read-only* privileged* 

Entry Point : CZCYG1 -- Entered via type-1 
linkage. 

Input ; Register 1 contains the address of 
a two-word parameter list: 

Word 1 — Address of DCB being closed. 

Word 2 — Address of associated JFCB. 

Data References ; CHADCB, CHATDT, CHASDA, 
CHADEB, CHMSA # CHADEC. 

Modules Called ; 

Write (CZCYM) — TAM write* 

Check CCZCRC) -- Check. 

VMA CCZCGA) -- Free virtual storage* 

ABEND CCZACP) — Abnormal task termination* 

WTO CCZABQ) — Write to operator. 

SETAE CCEAAK) ~ Set asynchronous entry. 

ADDEV (CEAAC) — Add device to task device 
list. 

RMDEV CCEAAD) — Remove device from task 
device list. 



XTRCT (CEAH3) — Extract TSI field. 

SY5ER (CEAIS) — System error. 

Exits : 

Normal -- Return to calling routine. 

Error — 1. ABEND macro instruction. 
2. SYSER. 

Operation : TAW Close initially saves the 
general registers. The Recursive Call flag 
is tested to prevent a recursive loop 
between TAM Close and ABEND- If the flag 
is set, it indicates that this is a recur- 
sive call. This means that just prior to 
this entry to TAM Close C through Close Com- 
mon) from ABEND, and exit from TAM Close to 
ABEND occurred. TAM Close therefore does 
not proceed but only clears the Recursive 
Call flag and branches to ABEND. 

If the Recursive Call flag is not set, 
the opened DCB count in SDAT for this ter- 
minal is decremented by 1 Cfor this DCB) 
and the number of opened DCBs that are 
still open for this terminal is examined. 

If the number is positive, the pages of 
virtual storage created for this DCB are 
freed, and the pointers that were set dur- 
ing TAM Open are removed. CSee TAM Open 
Figure 4.) A return is then made to Close 
Common. 

If the number is zero, processing con- 
tinues. (This indicates there is now no 
opened DCB for this terminal.) 

If the number is negative, the recursive 
call flag is set, a count of zero replaces 
the negative number and processing con- 
tinues as if there were a zero count* 

Processing continues with this terminal 
no longer having any opened DCB. A test is 
made to determine if the interruption 

storage area (ISA) flag is set with ABEND-- 
2. If it is not* TAM Close continues test- 
ing the terminal to determine the type of 
close. 

If it is set, then TAM Close immediately 
goes to the final steps of a close. 

Note : ABEND=2 indicates that the entry to 
this closing came from ABEND and, after the 
closing, a return is made to ABEND. When 
this return is made, ABEND retains control 
of the terminal. 

Testing continues at this point to 
determine the type of close by verifying 
that the terminal is defined and, if so, if 
it is on a 2702. 

If it is defined and is not on a 270 2, 
TAM Close proceeds with the final steps of 
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a close, bypassing the disable/enable func- 
tion. (The terminal defined in this manner 
is the operator's terminal; a 1052-7 direct 
connection to the multiplexor channel.) 

If it is supported and is also on a 
2702, then the disable/enable function is 
required. Initially, after checking that 
the device has not been phased out, proces- 
sing takes place to provide a SYNAD address 
for the disable/enable function. The SYNAD 
address in the user's DCB is saved in a 
temporary area within TAM Close and is 
replaced with a TAM Close SYNAD address. 
Should any I/O operation fail during the 
disable/enable function the SYNAD will 
either declare a minor SYSER software error 
or abnormally terminate the task. In all 
error cases the task is abnorma.lly ter- 
minated. At this point the terminal is 
disabled and TAM Close must then enable the 
line. In order to enable the line, TAM 
Close reopens the DCB Cby setting the DCB 
open flag) that was previously closed in 
Close Common. After performing the follow- 
ing functions , TAM Close closes the DCB 
again with the disable/enable function com- 
pleted and the user's SYNAD address 
replaced. The following functions are 
required in order for TAM Close to enable 
the line: 

• The disabled terminal must be added to 
the task. 

• Asynchronous interruptions must be 
ignored when the disabled terminal is 
connected to the task. 

• The terminal control unit must be 
restored to the initial SAD order. 

• The line is then enabled* 

• The terminal is removed from the task. 

If it is not defined, then the Recursive 
Call flag is set and TAM Close proceeds 
with the final steps of a close, bypassing 
the disable/enable function. 

In the final steps of a close, the pages 
of virtual storage created for this DCB are 
freed and the pointers that were set during 
TAM Open are removed Csee Figure U). 

A final test is then made of the Recur- 
sive flag. If it is on, a message is 
issued to the operator and ABEND is 
invoked. If it is not on, a return is made 
to Close Common. 

IOR Close Routine (CZCSD) 

IOR Close is called by Close Common: 



• Due to normal completion of a task. 

• Due to ABEND requirements for a task to 
be closed. 

In continuing the close processing from 
Close Common, IOR Close is called to per- 
form additional functions for these 
devices. IOR Close waits until all out- 
standing DECBs have been completed and then 
frees the IOREQ work area, DEB and lORCB. 
IOR Close then returns to Close Common. 
CSee Chart DF. ) 



Attribute s : Reentrant, resident in virtual 
storage, closed, read-only, nonrecursive, 

privileged. 

Entry Point ; CZCSD1 — Entered by type-1 
linkage. 

Input : Register 1 contains the address of 
a two- word parameter list: 

Word 1 — Address of DCB being closed. 

word 2 -- Address of associated JFCB. 

Data Reference : CHADCB, CHADEC, CHADEB. 

Modules Called : 

VMA (CZCGA) — Free virtual storage. 



AWAIT CCEAP7) 



Await an interruption. 



DIR (CZQJD) -- Delete asynchronous inter- 
ruption requests pending. 

Exit : Normal return to calling program. 

Operation : IOR Close initially saves the 
general registers. The address of the DEB 
CDCBDEB) is obtained from the DCB. A test 
for any unchecked DECBs is made. 

• If there are no unchecked DECBs 
(DEBNPC=0) , processing continues by 
determining the area to be freed. 

* If any DECB is unchecked (DEBNPC*0), 
the address of the last DECB in the 
queue is obtained (from DEBDEL) . The 
AWAIT SVC is moved into this DECB and 

the IOR Close executes (EX) the AWAIT 
in this DECB. IOR Close then waits 
until this last DECB is posted complete 
CDECECB), and then processing continues 
by determining the area to be freed. 

In determining the area to be freed the 
size of the DEB is added to the size of the 
IORCB and then a FREEMAIN macro instruction 
is issued to free the area. The final step 
of IOR Close is to return to Close Common. 
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SECTION bj 



ROUTINES SPECIFICALLY DESIGNED FOR BSAM 



LABEL PROCESSORS 

The following routines describe tape and 
direct access input and output label 

processors • 

Tape Volume Label Routine (CZCWX) 

The Tape Volume Label routine is called 
by Device .Management to read a tape volume 
label, or to rewind and unload a tape. It 
may also be called by Device Management or 
the LABEL command routine to write a volume 
label (Chart EA) . 

Entry Points : 

CZCWX1 — Entered to read the volume label. 

CZCWX2 -- Entered to rewind and unload a 
tape. 

CZCWX3 -- Entered to write the volume 
label. 



Operation : The text of the 'Operation' is 
keyed to the labels of Chart EA. 

A Read is entered at CZCWX1, a Write at 
CZCWX3. Tape Recording Technique, density s 
BPI are set (CA001), a temporary DEB built 
CCA001A) and the tape rewound (CA002). 

CZCRAS reads the label for a Read option 
and returns on normal completion or returns 
a code as described under 'Exits 8 (CAOOUC - 

CA008A). 

CZCRAS writes a number of tape marks if 
the first word of the buffer is blank, or 
writes a label. An American National Stan- 
dard format label is written where ASCII is 
specified- The label write will be fol- 
lowed by a write of tape marks. If CZCWX 
was called by Pause, two tapemarks are 
written; otherwise, five tapemarks are 
written Cvia five calls to Control) CCAOCM 
- CA004A - CA008 - CAOOSE). 



Input : Register 1 contains the address of 
the following parameter lists 

Word 1 — Address of the SDAT. 



If CZCWX was called by PAUSE, the file 

is backspaced past the tape marks. If not 

called by PAUSE, it is rewound and unloaded 
CCA0OSF ~ CA005ti) . 



Word 2 -- Address of an 8 0-character label 

buffer. 

Word 3 — Address of a 1-byte field con- 
taining the density setting* 

Word U — Address of a 1-byte field con- 
taining ASCII/EBCDIC indicator (X s 20 s = 
ASCII; X'OO 8 = EBCDIC). 

Modules Called : 

Control (CZCRBS) ~ Rewind, rewind and 
unload f write Tape Mark, or backspace. 

GETMAIN CCZCGA2) ~ Get a work page* 

Read/Write (CZCRAS) — Read a block* write 
a label* 



Exits; 



Return Code 
00 

08 
0C 



Condition 
Normal return, or in- 
correct length on READ 
or WRITE. 

Intercepted more than 10 
tiroes, or unit check with 
no file protect • 

Unit exception. 

Unit check with file 
protect . 



At CZCWX 2, a temporary DEB is created 
and CZCRB is called to rewind and unload 
the tape. 

Various return codes reflect the possi- 
ble READ/WRITE errors. (See 'Exits 8 . ) 

Tape Dat^JSet .babel Rout ine (CZCWY) 

This routine reads and writes data set 
header and trailer labels on magnetic tape 
volumes. / Error checking is provided after 
reading labels. User label routines are 
called if required. Provision is made for 
reading and writing labels in either stan- 
dard IBM or American National Standard for- 
mats. (See Chart EB. ) 

Attributes : Reentrant 9 resident in virtual 
storage, read only, public* privileged f 
system* nonrecursive. 

Entry Points ; 

CZCWYl -- Entry point for processing header 
labels for input data sets. 

CZCWY2 — Entry point for processing trail- 
er labels for input data sets. 

CZCWY3 — Entry point for processing header 
labels for output data sets. 

CZCWY4 — - Entry point for processing trail- 
er labels for output data sets. 
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Input s Register 1 contains the address of 
a parameter list consisting of the address 
of the SAM communication block, CHASCB. 
CHASCB includes SCBIOA, which point** to on 
80- byte buffer area. Fields of special 
interest reached through CHASCB: 

DCGOFG (Open Flag - DCB03M) which may 
contain: 

Data set being opened or closed. 

1 Data set open, EOV process, 

DCBOFG (EOT Flag - DCB06M) which may 
contain: 

Process on basis of open flag. 

1 EOT occurred while writing EOF 
labels - write EOV this time. 

DCBOPT (Option - DCBSU2) which may 
contain: 

Standard IBM labels (EBCDIC 
user) . 

1 American National Standard labels 
(ASCII user) . 



TDTSUM) which may 



TDTLAB (Labels 
contain: 

No user labels. 

1 Process user labels. 

Data References : CHASCB, CHADCB, CHADEB, 
CHADEC, CHAISA, CHALB1 , CHALB2, CHASDA, 
CHATDT. 

Modules Called : 

BSAM Read/Write (CZCRA) — Read or write a 
physical record. 

Control (CZCRB) -- Provide non-data opera- 
tions on the tape device. 

LVPRV (CZCJL) ~ Provide type-3 linkage to 
nonprivileged user label routines. 

User Prompter (CZCTJ) — Communicate with 
user. 

Volume Sequence Convert (CZCWV) -- Compute 
the address of the volume serial field 
of JFCB specified by relative volume 
sequence number in SCBRVS . 

Exits : 

Normal — • Return to calling program with 
return code in register IS. 

Error -- Link to CZACP (ABEND) with regist- 
er 1 pointing to message area, first 
byte of which contains the length of the 
message text. 

Operation : An initialization section used 
in common from all four entry points per- 
forms standard linkage and save require- 
ments and establishes addressability. A 
branch table containing the addresses of 
the four separate labeling routines is 
encountered, and the appropriate label pro- 



cessor reached based on a code saved upon 
entering Tape Label Processor at one of the 
four entry points. 

Proceeding for each of the four labeling 
routines is discussed below separately. In 
addition, three subroutines, Build, a rou- 
tine which actually builds the tape label 
in a buffer for output. Check, which deter- 
mines processing after a label I/O opera- 
tion has occurred, and SUL, which handles 
user labels, are described. 

Input Header Label Processor (CZCWY1) : The 
tape label is read and the read checked by 

a branch to the Check subroutine. If a 
read error has occurred, or a tape mark or 

the beginning of the tape is encountered, 
an abnormal end is made. If the label is a 
volume label, another read is issued. If 
the label is not a volume label, and is not 

a HDR1, E0V1, or EOF1 label, an abnormal 
end is made. 

If the label is HDR1, EOV1, or EOF1, the 

block count is stored in the DCB. The 
DSNAM subroutine is entered to check the 17 
least significant characters of the data 
set name against those in the JFCB. The 
user is notified through the PROMPT macro 
instruction when the data set names in the 
label and the JFCB do not agree and given 
the option to continue or to terminate by 
an abnormal end* 

If the generation/version numbers are 
not correct, the user, as above, has the 
choice of terminating or continuing. 

The next label is read and the read is 
checked. An abnormal end termination is 

made if a read error occurs. If a tape 
mark is read during a read backward opera- 
tion, the routine backspaces the tape to 
position it for a data set read. If the 
label wars an HDR2, an EOF2, or an EOV2, and 
if the record format, record length, and/or 
block size in the CHADCB are zero, the rou- 
tine obtains the information from the 
label, converts it to binary, and stores it 
in the DCB. If the user has indicated his 
data set is in ASCII, the HDR2 label will 
have a buffer offset field. Unless this 
field contains zero, it will also be con- 
verted to binary and stored in an appropri- 
ate field in the DCB. 

If standard user labels are not speci- 
fied, or if they are specified but the user 
input header label exit is not active^ the 
tape is positioned to read the data set, 
and a normal return is made. 

With user labels specified, a branch is 
made to the SUL subroutine (explained 
below) . On return to the Input Header rou- 
tine, the tape is positioned to read the 
data set, and a normal return is made. 
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Input Trailer Label Processor CCZCMY2) ; 

This routine processes standard IBM CEBCDIC 
users) and American National Standard 
(ASCII users) trailer labels for an input 
data net being read forward, and header 
labels for an input data set being read 
backwards. User labels are also piocessed. 

The routine first reads and checks the 
label. If an error or tape mark is encoun- 
tered during the read operation, or if the 
label read was invalid, the abnormal end 
code is set in the CHASCB, and an abnormal 
ei.ri is effected. 

If a volume label was read # the read is 
reissued. 

If the block count of the CHADCB does 
not equal that in the label, the user is 
informed, and a reply is expected* The 
user may elect to terminate the task. 

If standard user labels are specified, 
and the exit is active, another READ is 
issued and checked* Again, if a read error 
was encountered, the abnormal end code is 
set and an abnormal end is effected. The 
READ is reissued if an HDR» EOF, or EO¥ 
label is encountered. Otherwise* the user 
is given the facility to process the label. 

User labels are read and checked by the 

SOL subroutine* 

Output Header L abel Processor CCZCWY3) : 
This routine checks the currently mounted 
output tape to see if the expiration date 
of any data set currently on the tape (and 
about to be overlaid) has been reached and 
oversees creation and writing of new output 
header labels in either standard IBM or 
American National Standard CASCII users) 
format. It sets up the mechanism for writ- 
ing up to eight standard user labels , or an 
unlimited number of user labels when ASCII 
is specified- 

On entry to this routine, the tape label 
is read and checked. If a volume label is 
encountered^ the next label is read; this 
label should be either a HDR1 label (from 
an old data set which we are overlaying) or 
a tape mark (if the tape is clean). Where 
neither is encountered, abnormal termina- 
tion occurs. 

If HDR1 was present, the expiration date 
of that data set is checked and if it has 
not yet been reached, the user is prompted. 
He may choose to continue or request 
abnormal termination* 

The logical file (data set) sequence 
number is taken from the JFCB # the tape is 
repositioned to write the header labels , 
and the Build subroutine called to write 
both HDR1 and HDR2 labels. 



If user labels have been requested, a 
branch is made upon return from Build to 
the SUL subroutine. 

On return from SUL f the Control subrou- 
tine is called to write a tape mark follow- 
ing the header label group and position the 
tape to write the data set. Normal return 
is made to the caller* 

Output Trailer Label Processor (C Z CWY4) : 
If CLOSE processing is being done, the 
characters B0F1 are placed in the first 
four bytes of the 80 character label buff- 
er. Otherwise, this routine must have been 
called for an end-of-tape condition, and an 
E0V1 is placed there. The remainder of the 
label is created and written by a branch to 
the Build subroutine. Build writes the two 
trailer labels in either standard IBM or 
American National Standard label format. 

The SUL subroutine is called if user 
labels have been requested. Control is 
called to write a tape mark and position 
the tape- Normal return is then made to 
the caller. 

Bu i Id 5 u br o ut i n e : This routine builds 8 0- 
byte output header and trailer labels ioi 

tape volume data sets and writes them by 
calling BSAM Read/Write. 

The routine expects the first four bytes 
of the 80-byte label buffer to already con- 
tain HDR1 Cfor header labels), or E0F1 or 
EOV1. {for trailer labels). Build filli.- ;:. 
the remaining bytes as shown in Table 21, 

Initially, after moving the 17 least. 
significant characters of the data set name 
to the label buffer, the Volume Sequence? 
Convert routine is called to compute the 
address of the volume serial field of the 
JFCB. The data set serial number is 
obtained from this field if the volume is 
not mounted, or from the SDAT if it is. 

Then f in order, the relative volume 
sequence number f the data set sequence 
number f generation and version numbers, 
creation and expiration dates 9 block count, 
and system code are moved into the label 
buffer. The data set security number fxelu 
is made blank for American National Stan- 
dard CASCII users) label format or a 
character zero for standard IBM format. 

Build then branches to the Write subrou- 
tine in Tape Data Set Isabel which calls 
BSAM Read/Write to write the first label on 
the tape. The Check subroutine determines 
tape write errors or end of tape and passes 
that information back to Build* Build now 
sets the label number to two and makes up 
the second label, illustrated in Table 22. 
The standard IBM and the American National 
Standard second label formats are similar 
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Table 21. Label 1 Fill Table 



Label Field 


Size In 
Bytes 

. H 

1? 


Filled | 
Fro* 

_ H 

CHATDT 
(JFCB) | 


Remarks j 

17 least significant j 
characters of M ) 
character Data Set j 
Name in the Job Fi le I 
Control Block | 


Data set Identifier 


Data Set Serial 
Muter 


t 


CHASDA 
or JFCB 


Filled from Voluae ID \ 
field of CHASDA if | 
volume is raounted, | 
otherwise fron Volume j 
ID field of first | 
Volui»e Serial field I 
in the Job File | 
Control Block j 


Voio»e Sequence 
Number 


u 


CHASCB 




Data Set Sequence 
HTuiRber 


u 


CHATOT 

(JFCB) 




Generation Number 


«j 


CHATDT 
(JFCB) 




Version of 
Generation 


2 


CHATDT 
(JFCB) 




Creation Date 


6 


CHATDT 
(JFCB) 




Expiration Date 


e 


CHATOT 
(JFCBJ 




Data Set Security 

mmimx 

CAccaaaibilityl 


i 


__ 


Not Inpleaented I 
Cblank if ANS,- *ero 1 
if standard IBM) | 


Block Count 


6 


CHADCB 




Systeai Code 


13 


- 




Res erred 


? 


„ 


Filled with blanks | 
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except for the buffer offset field which 
roust be filled in for the American National 
Standard format. 

The routine effects an abnormal end it 
there is a tape write error in writing 
either label. If, on attempting to writ.* a 
header label, an end-of-tape indication s 
detected, an EOV trailer label is written 
inst€-ad and the header label is written on 
the next volume. 

A more detailed discussion, including 
tables, of both standard IBM and American 
National Standard label formats, is con- 
tained in Appendix A of Data Management 
Facilities , GC28-20S6. 



SUL Subroutine ; This routine reads and 
writes user labels. Standard IBM format 
users; may have a maximum of eight user 
labels; ASCII users, who must conform to 
the American National Standard label for- 
mat, are allowed in TSS/360 to have a numb- 
er of user labels limited only by the phys- 
ical extent of the tape volume . 

Initially, the routine calling SUL will 
have placed UHL1 (user header label) or 
UTL1 (user trailer label) in the label 
buffer- SUL will then determine from a 
code passed in register 1 whether to read 
or write. If a user label is to be read, 
the Read subroutine will be branched to for 
reading and checking a user label. An 
abnormal termination will occur if the 
label read is neither a header or trailer 
label. The user's label processor will 
then be called. 



Table 22. 


Label 


2 


Fill Table 


| Label Field 




| Size In | Filled \ j 
| Bytes | Fro* j Remarks j 


( Record Foriaat 




i 1 




| CHADCB | ( 


| Block Length 




1 * 




I CHADCB [ | 


j Record Length 




t 5 




I CHADCB | f 


j Density 




I 1 




I CHADCB I \ 


j Data Set Position 


1 1 




f -- I contains if first \ 
j | voluae counted, { 
| I otherwise contains 1 | 


| Job/Step 

| Identification 




f 17 




\ -~ I OS only | 


\ Tape Recording 
| Technique 




I 2 




{ CHADCB | I 


I Print Control 
| Character 




1- 1 




| CHADCB J | 


| Reserved 




| 13 




| -- j Contains Blanks | 


1 Buffer Offset 




t 2 




1 CHADCB 1 ANS labels (ASCII) j 

| ( only," otherwise | 

J | reserved | 


| Reserved 




| 28 




I -- | Contains blanks | 

1 !._..- ,_J 


r- — — 

| TOTAL 

i. , 
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Where a label is to be written, the 
user's label processor will be called first 
to build the rest of the label in the label 
buffer, and then SUL will cause the label 
to be written and checked. 

If the user is nonprivileged, his user 
routine is not called directly; he gains 
control through the Leave Privilege 
routine. 

When the user labels have all been read 
or written (a maximum of eight for EBCDIC 
users, no maximum for ASCII users) , return 
is made to the routine which called SUL. 



Check Subroutine: 



This routine is entered 



following a return from BSAM Read/Write to 
check the I/O operation results and deter- 
mine further processing. 

Check inspects various fields and flags 
in the data event control block and sets 
the return code as follows: 
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I OPERATION CHECKED 

( READ i 



WRITE 



1 Normal Complete 

I 

fUnit Exception 

I 

S Error 

i 

| Intercepted 

1 

| Unit Check 
1 (Beginning of 
j Tape) 

L__„ — _ — — .— .— 



4Rtn. 
Code 

.„„ _„ + —- H 

Normal Complete) 8 00 * 



, Error 

i Intercepted 

(Unit Exception 



'04' 

•08* 
*0C* 
s 10 s 



If the operation is intercepted, the 
routine sets a counter so that a maximum of 
50 interceptions on this operation is 
allowed before the return code is set to 
the error code. 

If the operation is not complete, the 
AWAIT macro instruction is used to allow 
the operation to complete. 

DA Input Lab el Ro utine CCZCXN) 

The Direct Access Input Label processor 
reads standard direct access user header or 
trailer labels, and provides linkage to a 
user label processing routine as specified 
in the DCB exit list. (See Chart EG.) 



Attributes: 



Reentrant, nonrecursive, resi- 



dent in virtual storage, privileged. 

Entry Point : CZCXN1 -- Entered via type-1 
linkage. 

Input : Register 1 contains the address of 
the SAM communication block. 

Data References ; CHASCB, CHADEB, CHADCB, 
CHAISA. 

Modules Called : 

Message Writer CCZCWM) — Message proces- 
sing and ABEND processing. 

Obtain/Retain (CZCFO) — Obtain DA user 
label. 



LVPRV CCZCJL) 



Leave privileged state. 



Exi t : 

Normal 



Return to caller. 



Error — Call Message Writer to do ABEND 

processing . 

Operation : Standard user labels are read 
via Obtain* and, if the user is non- 
privileged, processing is provided for via 
the Le^atve Privilege routine (LVPRV). 
Figure 8 shows Obtain keys and Label I/O 



UHL in) 

or 
UTL fn) 


UHL (n) 
or 

UTL fni 




CCHHR0O0 


Obtain t*ey 


User t< be! i«ey 


Mlice Moneoj* 
Usef Oafo 


Dlrec 1 Access 
Addreis 


4 


4 


76 


8 



Figure 8. Obtain Keys and Label I/O Areas 



area. When a file mark is read, or the 
user returns a zero code from LVPRV, the 
routine places a zero code in general 
register 15 and returns control to the 
invoking program* 

If the exit type in SCBEXT is not for 
input user header or trailer labels, the 
routine sets a unique ABEND code in SCBABN, 
and links to the Message Writer for ABEND 
termination* 

If there was a hardware error while 
attempting to read a label, the message 
•XXXX LABEL UNREADABLE, ENTER N TO READ 
NEXT LABEL, B TO BYPASS LABELS OR E TO END 
THE TASK" is sent to the user via the Mes- 
sage Writer routine. If the user replies 
"N", and there have not been eight attempts 
to read labels, reading of the next label 
is attempted. 

If eight attempts have been made, or if 
the user replies m B m , control is returned 
to the caller with a zero return code in 
general register 15. If the user replies 
"E" # the routine sets a unique ABEND code 
in SCBABN and calls the Message Writer rou- 
tine to perform ABEND termination. 



DA Output Label Routine (CZCXU) 

The Direct Access Output Label processor 
provides the user with the facility for 
building and writing standard user labels 
on a direct access device. (See Chart EH. ) 

Attributes ; Reentrant, nonrecursive, resi- 
dent in virtual storage, privileged. 

Entry Point : CZCXU1 -- Entered via type-1 
linkage. 

Input ; Register 1 contains the address of 
the SAM communication block . 

Data References : CHASCB, CHADCB, CHADEB. 
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Modules C alled i 

LVPRV (C2CJL> — Loavc pnvii«*qed state. 

Obtain/Retain (CZCFO) — Retain DA user 
label. 



Kxits : 

Normal — Return to caller with '00* in 
general register 15. 

Error — Register 15 contains " 0***. 



Operation ; If there is a label track in 
the first extent of the data extent block, 
and an output label type is specified in 
the CHASCB, and the exit type is active, 
the user is given the facility to build 
labels via the Leave Privilege routine, and 
to write labels via Retain, until the user 
passes a zero return code in general 
register 15, or until eight labels are 
written. At that time, a file mark is 
written via Retain. CSee Figure 9 for the 
RETAIN keys and the LABEL I/O area.) 

If the exit type specified in the CHASCB 
is not for output header or trailer labels, 
a unique ABEND code is set in the CHASCB, 
and control is returned to the caller with 
a return code of *QM* in general register 
15. 

If Retain returns with a code other than 
zero in general register 15, a unique ABEND 
code is set in the CHASCB, and control is 
returned to the caller with a return code 
of f 0<* f in general register 15. 



EOV PROCESSORS 

End of volume processing consists of 
tape and direct access input and output EOV 
routines, mainline and f forced* EOV rou- 
tines, and concatenation and check proces- 
sors- The EOV routines are entered as the 
result of one of two conditions: end of 
data set or end of volume. 



UHL (n) 

or 
UTL (n) 


UHL (n+ 1) 

or 
UTL (n ♦ 1) 




CCHHR000 


Reroin key 
4 


User (abet key 
4 


Miscellaneous 

User Data 

76 


Direct Access 
Address 
8 



Figure 9. Retain Keys and Label I/O Areas 



E9 F .£? J°?J}§„ of V o lu me jRo u t in* * CCZC LD) 

The Force End of Volume routine ter- 
minates the processing of the current 
volume of a data set, and prepares for the 
processing of the next volume. it accomp- 
lishes this by initiatinq the Knd of Volume 
(EOV) routines. (See Chart FA.) 

Attributes : Reentrant, resident in virtual 
storage, closed, privileged, read-only, 
public. 

Entry Point : CZCLDF — Entered by type IM 
or type IIM linkage. 

Input : Register 1 contains the address of 

the DCB. 

Data References : CHADCB, CHADEB. 

Modules Called : 

SAM Mainline EOV (CZCXE) — SAM Mainline 
end of volume processor. 

QSAM FEOV CCZCSA) -- QSAM forced end of 
volume processor- 

Exits : 

Normal — Return to calling routine. 

Error — ABEND macro instruction. 

Operation : Force End of Volume abnormally 
terminates the task via the ABEND macro 
instruction for any of the following 
reasons: 

• DCB identifier is not valid. 

• Data set is not physical sequential. 

• Data set is not on magnetic tape or DA. 

• Not all BSAM DECBs have been checked. 

Control is returned to the calling routine 
when the input DCB is not open. 

Should all of the above tests be passed 
and if QSAM, QSAM FEOV is entered. If not 
QSAM, or on return from QSAM FEOV, the FEOV 
flag is set on and the Mainline EOV routine 
is entered. When Mainline EOV returns to 
Force End of Volume, control is then 
returned to the calling routine. 

Note the function of this routine is 
mainly performed by Mainline EOV. 



Mainline EOV Routine (CZCXE) 

Mainline EOV performs as a control pro- 
gram to End of Volume CEOV> processing. It 
oversees the modifying of the DEB, label 
processing, volume switching, determining 
end of data set, concatenation processing , 



Section 6: Routines Specifically Designed for BSAM 79 



and pausing control to user label exit rou- 
tines. (See Chart FB. ) 

Attributes : Reentrant, resides in virtual 
storage, closed* read-only, privileged. 

Entry Point : C2CXE1 -- Entered by type-1 
linkage. 

Input : Register 1 contains the address of 
the DCB causing EOV involvement* The PSECT 
contains CHASCB and three temporary control 
blocks for use in the I/O operations of 
label process ing« 

Data References : CHADCB, CHADEB, CHASCB, 
CHATDT, CHADEC, CHAISA. 

todules Called : 

VMA (CZCGA) -- Get virtual storage, free 

virtual storage. 

Build Common DEB CCZCWB) ~ Restore the 
common portion of the DEB. 

Volume Sequence Convert CCZCWV) ■ — Volume 
address convert. 

DA Input EOV (CZCXD) -- Direct access out- 
put end of volume processing* 

DA Output BOV CCZCX1) — Direct access 
input end of volume processing. 

Tape Output LOV (CZCXO) -- Tape output end 
of volume process ing*. 

Tape Input EOV (CZCXT) — Tape input end of 
v o 1 urn e pr o c e s :-■ i ng . 

User Prompter CCZCTJ) — - Communicate with 
user, 

AWAIT (CEAP7) ■ — Await an interruption. 

Exits : 

Normal — Return to calling program. 

Error — 

• Call User Prompter to inform user. 

• Via ABEND. 

Operation : The SAM control block (CHASCB) 
is initialized by zeroing the variable 
fields, storing pointers to the input DCB, 
JFCB, and DEB, and storing the volume 
address in the volume serial field of the 
SCB. The pointers to the JFCB and DEB are 
known because the input DCB contains a 
pointer to the DEB, and the DEB points to 
the JFCB. 

Mainline EOV assures the DEB pointed to 
by the DCB has a valid DEB- id, and that the 
DEB points to the DCB passed. If not, the 
routine abnormally terminates. 



The routine initializes the temporary 
DCB and DEB for use by SAM routines called 
by SAM EOV. End of data set is indicated 
for non-concatenated unit-record data sets. 



If ttw tlovico is tape, the temper a iy 

mtrol block;; are adjusted no tape* l«%brls 
y be read or written. For DA devices, 

,e temporary DCB is set so user labels may 



cout 

ma 

the tempora.^ _ 

be read or written. In either case, tape 

MAI., *W WW.^*^Vl WW ^w -„ K *. 

storage for a label buffer 



DA, if user labels are specified, GET- 
EN is called to get unprotected virtual 



Depending on whether the device is tape 
or DA, and whether the last I/O operation 
was input or output , Mainline EOV branches 
to Tape Output EOV* Tape Input EOV, DA Out- 
put EOV, or DA Input EOV routines. 

When the device-oriented EOV routine 
returns control to .Mainline EOV, any 
storage which had been obtained for label 
buffers and format~3 DSCBs is released via 
FREEMA1N. 

If no abnormal conditions occurred dur- 
ing EOV processing, control is returned to 
the calling routine. 



' Ta pe Input EOV Routine (CZCXT) 

The Tape Input EOV routine executes the 
end-of -volume procedures for the mounted 
input magnetic tape volume • That is, it 
oversees label processing and final volume 
positioning. If the mounted volume is only 
one of a multivolume data set. Tape Input 
EOV causes the next volume to be mounted, 
oversees positioning and label processing 
of the new volume, and updates the DEB to 
reflect the presence of the new volume* If 
the data set is a member of a concatenation 
of data sets, the Concatenation routine is 
used. (See Chart FC.) 



Attributes ; Reentrant, resides in virtual 
storage, closed, read-only, privileged* 

Entry Point : CZCXT1 -- Entered by type-1 
linkage. 

Input ; Register 1 contains the address of 
the SAM communication block. 

Data References ; CHADCB, CHADEB, CHASCB, 
CHATDT. 

Modules Called ; 

Control (CZCRB) — Tape positioning. 

Bump (CZCAB) — Request and verify mount of 
new volume. 

Build Common DEB CCZCWB) — Modify the com- 
mon portion of the DEB. 
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Tape Data Set Label (CZCWY) — Tape label 
processor . 

BSAM Read/Write CCZCRA) -- Read ahead for 
tape mark. 

User Prompter (CZATJ) — Send message to 
user. 

Tape Positioning CCZCWP) — Tape 
positioning. 

Volume Sequence Convert (CZCWV) — Volume 
address conversion. 

Concatenation (CZCXX) — Concatenation, 

Exits ; 

Normal — Return to calling program. 



T ape Output EOV Routine (CZCXO) 

When a data set is being closed, Tape 
Output EOV oversees the end-of-volume tape 
processing, including the writing of trail- 
er labels. For multivoiume output data 
sets, this routine oversees the mounting of 
the new volume and updating of the DEB. 
(See Chart FD. > 

Attributes : Reentrant, resides in virtual 
storage, closed, read-only, privileged. 

Entry Point : CZCXOl — Entered by type-1 
linkage. 

Input : Register 1 contains the address of 
the SAM communication block which was 
generated in the PSECT of Mainline EOV. 



Error — Call Message Writer to do ABEND 
processing . 

Operation ; For forced end-of-volume condi- 
tions, Tape Input EOV proceeds as if the 
EOV condition was encountered for unlabeled 
tape. 



Data References : CHADCB, CHASCB, CHATDT. 

Modules Called : 

Control CCZCRB) -- Tape positioning. 

Bump CCZCAB) -- Request and verify mount of 
new volume. 



The tape is properly positioned via the 
Control routine. 



Build Common DEB CCZCWB) — Modify the com- 
mon portion of the DEB. 



When trailer labels are present, Tape 
Data Set Label is called at entry point 
CZCWY2 to process user trailer labels and 
standard trailer labels. 

Unless a read backward operation was 
performed, a READ is issued to check for a 
second tape mark, indicating end of tape. 
Otherwise, end of data set processing is 
required. The tape is repositioned via 
CONTROL. 

If this is the last volume, and there is 
no concatenation, the End of Data Set flag 
is set in the DCB and control is returned 
to the calling routine. 

The Concatenation routine is invoked if 
concatenation is indicated. For a non-end- 
of-data-set condition, the Bump routine is 
used to mount the next volume. The DEB is 
updated via Build Common DEB to reflect the 
new volume and the Tape Positioning routine 
is used to position the tape for proces- 
sing. If the newly mounted tape has 
lables, the Tape Data Set Label is called 
at entry point CZCWY1 to process standard 
labels and user header labels. Tape Input 
EOV then returns control to the calling 
routine. 



Volume Sequence Convert (CZCWV) — Volume 
address conversion. 

Tape Data Set Label (CZCWY) — Tape label 
processor. 

User Prompter CCZCTJ) — Communicate with 
user. 

Exits : 

Normal — Return to calling program. 

Error — Via ABEND macro instruction. 

Operation : Tape Output EOV turns off the 
FEOV flag in the DEB and, via the Control 
routine, writes a tape mark on the tape. 
If labels are specified, the Tape Data Set 
Label is called at CZCWY4 to write user and 
standard volume trailer labels. Another 
tape mark is written and the volume posi- 
tioned immediately before the tape mark. 

Tap* morki written by Tap* Inpu' f OV 



R User Labels 

g| 



Volume Lobe 1 1 



The routine abnormally terminates when 
Bump indicates that the requested volume 
has not been mounted, or when the relative 
volume sequence of the volume to be mounted 
is less than the volume sequence number of 
the current volume. 



if the data set is being closed, normal 
return is made to the user. 

Otherwise, the address of the next 
volume is obtained by Volume Sequence Con- 
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vert* the volume just ended is rewound by 
Control $ and the volume is mounted by the 
Bump routine. The DEB is updated via Build 
Common DEB to indicate the presence of the 
new volume and if labels are specified* the 
user and standard header labels are pro- 
cessed by the Tape Data Set Label. 

Where an end-of -volume indication is 

received while the EOF trailer label is 
being written, the trailer label is rewrit- 
ten to contain EOV .instead* The EOF trail- 
er label is then written by the Tape Data 
Set Label at the beginning of the newly 
mounted volume following its volume and 
header labels. 

This routine abnormally terminates when 
Bump returns an error code indicating that 
the requested volume was not mounted , or 
when there is an incorrect volume sequence 
number. 



Concatenation (CZCXX > 
data sets. 



Concatenation of 



Exits : 
Normal 

Error - 



Return to caller. 



Call User Prompter or ABEND. 



Operation : If the integrity bit is on, or 
if a write was previously executed on the 
volume on which the EOV condition was 
encountered, a call to SETDSCB is provided 
to rewrite the format- 1 DSCB with the inte- 
grity bit off and also to write a file mark 
if this is indicated. 

Input user labels are processed by a 
call to the DA Input Label routine. 

If all volumes have been processed and 
concatenation is not specified, end of data 
set is indicated* 



DA Input EOV Routine (CZCXI) 

When a data set is being closed. Direct 
Access Input EOV oversees the end- of -volume 
direct access device processing, including 
the reading of user trailer labels. For 
muitivolume input data sets, or data set 
members of a concatenation, this routine 
oversees the end-of- volume processing for 
the current volume , the mounting of the 
new, or next volume, and the updating of 
the DEB. (See Chart FE. ) 



Entry Point ; CZCXI1 -- Entered via type-1 

iink/Kje. 

Input ; Register 1 contains the address of 
the SAM communication block. 

Data References : CHASCB, CHATDT, CHADSC # 
CHADEB, C;iADCB.~ 

Modules Called : 

Bump CCZCAB) — Request and verify mount of 
new volume - 

Obtain/Retain CCZCFO) — - Obtain DA user 
label and retain DA user label. 

Build DA DEB CCZCWD -- Build direct access 
DEB, 

User Prompter CCZATJ) — Communicate with 
us e r - 

SETDSCB CCZCXS) -- Update DSCB and write 
file mark. 

Volume Sequence Convert CCZCWV) — Volume 
address conversion. 

DA Input Label CCZCXN) — Direct access 
input user label processor . 



Otherwise ff the Concatenation routine is 
called if concatenation is specified. If 
all volumes have not been processed , Bump 
is used to switch volumes. When the new 
volume is mounted* Obtain and Retain are 
called to read the DSCB and write the new 
DSCB respectively. The user is warned and 
given the option to continue if the inte- 
grity bit for the newly mounted volume is 
on. The new DEB is built by Build DA DEB. 



9A .. j^iLP!»!L- £9y. Jtout i H£ L£2cx 22 

When a data set is being closed. Direct: 
Access Output EOV performs end-of- volume 
processing, including the writing of user 
labels and release of available unused 
storage. For muitivolume output data sets, 
this routine oversees the acquisition of 
new extents and the updating of the DEB* 
(See Chart FF.) 

Attributes ; Reentrant , resides in virtual 
storage, closed* read-only, privileged . 



'Entry Poin t : 
linkage. 



CZCXD1 -- Entered by type-1 



Input : Register 1 contains the address of 
the SAM communication block. 

Data References ; CHADEB, CHADCB f CHATDT, 
CHASCB, CHADSC. 

Modules Called : 

Bump CCZCAB) — Request and verify mount of 
new volume. 

Extend (CZCEX) — Allocate additional DA 

space for a data set. 

Obtain/Retain (CZCFO) — Obtain direct 
access user label and retain direct 
access user label. 



82 Part I: Access Method for BSAM* MSAM f TAM and IOREQ 



Build DA DEB (CZCWL) 
direct access DEB. 



-- Build or modify a 



Message Writer (CZCWM) -~ Message proces- 
sing and ABEND processing. 



Read Format- 3 DSCBs (CZCWR) — Read and 
chain format- 3 DSCBs. 

Volume Sequence Convert (CZCWV) — Volume 
address convert. 

Set DSCB CCZCXS) — Update DSCB and write 
file mark. 

DA Output Label (CZCXU) — Write user 
labels for DA output data sets. 



Exits: 

Normal — Return to calling program. 

Error — Call Message Writer to do ABEND 
processing. 



Operation : The integrity bit is set on. 
If the data set is being closed, a request 
is issued for space or a volume switch. 

DA Output EOV uses Set DSCB and DA Out- 
put Label to write a file mark on the 
volume, reset the integrity bit, and pro- 
vide for user output label processing. 

Old data sets which exist on more than 
one volume and for which there is a suc- 
ceeding volume, have space allocated to 
them on the succeeding volume. 

On a forced EOV, DA Output EOV forces a 
volume switch. 

For new data sets, DA Output EOV 
attempts to get space on the currently 
mounted volume. If it cannot: 

• For priva€e data sets - If the data set 
is OLD or new, and this is the last 
volume of the data set, a demount/mount 
is requested, and allocation on the 
newly-mounted volume is attempted. 

When space is denied on the current 
volume. Set DSCB is used to write a file 
mark on the volume and to reset the format- 
1 DSCB integrity bit when volume switching 
is required. DA Output EOV uses the DA 
Output Label to allow user label 
processing. 

Build DA DEB is used to extend the DEB 
if space is allocated on the current 
volume; otherwise, when space is allocated 
on a new volume. Build DA DEB builds a new 

DEB. 



Concatenation Routine (CZCXX) 

The Concatenation routine is called to 
make the next data set of a concatenated 
group ready for processing. (See Chart 
FG. ) 

Attributes : Reentrant, resident in virtual 
storage, closed, read-only, privileged. 

Entry Point : CZCXX1 — Entered via type-1 
linkage. 

Input : Register 1 contains the address of 
the SAM communication block. 

Data References : CHASCB, CHADCB, CHATDT, 
CHADEB. 

Modules Called : 

Bump CCZCAB) — Request and verify mount of 
new volume. 

Open Common (CZCLA) — Common open. 

Close Common (CZCLB) -- Common close. 

ABEND CCZACP) — If bad return code from 
Bump. 

Exits : 

Normal — Return to the calling routine. 

Error — Call ABEND. 

Operation : The Bump routine is called to 
mount the first volume of the next data 
set. 

Close Common is called to close the cur- 
rent data set and Open Common is called to 
open the next data set. A return code of 
four is provided in the calling program. 

The routine abnormally terminates when 
Bump returns an error code. 



BSAM USER ROUTINES 

The following routines provide user con- 
trol of some aspects of direct access and 
tape devices. 

Note Routine (CZCRN) 

The Note routine provides the user with 
identification of the last record read or 
written. A relative track and record numb- 
er is returned, if the device is direct 
access, and a block count is returned for 
tape. All DECBs must be checked by the 
Check routine before Note is used. (See 
Chart GA.) 

Attributes : Reentrant, resident in virtual 
storage, closed routine, nonrecursive. 
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Entry Point : CZCRNA -- Entered via type-lM 
linkage. 

Input : Register 1 contains the address of 
the DCB, 

Data References ; CHADCB, CHADEB. 

Mo J^L i 1LIL Called : 

FULREL ICZCRS)" -- Convert full DA address 

to relative address. 



User Prompter CCZATJ) 
user. 



Communicate with 



Table 23. Decisions for Setting Block 
Count 



Last block read backward 



"-t~t-y~i 
|Y|N|N| 

I I I I 
DCBBCK^O | |Y|N| 

Add one to block count jxj | 

I I I 



Subtract one from block count 

Return with block count in 
register 1 



I |X| 
I I I 
I I 1 
|X|X|X 
-X-X-.JL-. 



Exits : 

Normal -- Return to the calling xoutine. 

Error -- ABEND termination. 

Ope ration ; Any data set which is not DA 
will be treated as if it were on magnetic 
tape- No error occurs when the Note rou- 
tine is entered for other than DA or mag- 
netic tape, but the address Note returns 
will not be meaningful for other devices* 

The routine ABENDS if the DCB is inva- 
lid. If all I/O has not been checked, the 
user is prompted to see if he wishes to 

continue. 

To obtain the relative address of the 
last record read or written on DA, the DA 
address of the last record is passed to the 
FULREL routine which converts the full DA 
address to a relative address. The rela- 
tive address is placed in register 1, and 
if the last I/O operation was a write, the 
number of bytes remaining on the current 
track is placed in register 0. 

For magnetic tape the Note address 
returned to the calling routine is a rela- 
tive block count* The block count is zero 
when the data set is opened to write. The 
first block is block 0, the second block is 
block l f the third block is block 2, etc. 
The relative block count is maintained Cfor 
the current record) in the DCBBLK* 

Table 23 indicates the block count which 
is set into register 1 for the calling pro- 
grain* The flag DEBRSB indicates if the 
last block processed was read backwards 
COP) or not (OFF) . 

Note: For magnetic tape volumes*- if the 
Note routine is entered after a Point macro 
instruction was executed and there is no 
READ or WRITE macro instruction between 
them, it returns the current relative block 
count plus one (if last I/O opeaation was a 
read backward) , or minus one Cif the last 
I/O operation was forward). The reason for 
this is that there is no change in the 
DCBBLK field since the last READ or WRITE* 
yet when Note is again entered it will per- 



form the calculation Cadding or subtracting 

one) on the relative block count anyway. 

Point Routine (CZCRM) 

The Point routine performs certain 
operations which cause the next read or 
write operation to be perforated at a speci- 
fied block in the current volume. The 
relative address of the block in question 
is passed to this routine as an input para- 
meter. The Point routine may be thought ol 
as a logical repositioning of the data set, 
(it is a real repositioning in the case of 
magnetic tape*) Point may only be used 
with DA and magnetic tape volumes- (See 
Chart GB.) 

Attributes : Reentrant, resident in virtua 
storage , closed routine f privileged. 

Entry Point : CZCRMA -- Entered via type-1 
linkage. 

Input : The following parameters are 
passed; 

Register -- Relative DA address f or rela- 
tive magnetic tape block address. 

Register 1 — Address of DCB« 

The relative block address should have 
been obtained by use of the Note routine. 

Data References : CHADEB* CHADCB. 

Modules Called ; 

RELFUL CCZCRR) - Convert a relative DA 
address to a full DA address. 

Control CCZCRB) -- Tape positioning. 

Exits: 

Normal — Return to calling program. 

Error -- ABEND termination. 

Operation : Point does not apply to devices 
other than DA or magnetic tape. Therefore, 
for other devices, normal return to the 
calling routine is made immediately. 
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Note always returns the relative address 
of the last block read or written. If the 
user wishes to point to that block, the Z 
byte should remain zero. 

When Point is entered for a DA device, 
the above mentioned flag (DEBIPT) is set if 
necessary, and the relative DA address is 
passed to the RELFUL routine. The RELFUL 
routine converts the relative address to a 
full DA address which is stored into the 
DEBNIO field. The DEBBP flag is set on to 
indicate to Read/Write that a Point opera- 
tion has occurred. 

When Point is entered for magnetic tape, 
if the tape volume is not currently at the 
requested postion, the Control routine is 
used to forward space or backward space the 
tape to the requested position. The dif- 
ference between the requested block count 
and the current block count is the number 
of blocks to be skipped. 

If errors occur during a point, DEBNF1 
j.S turned on so that subsequent reads or 
writes will be intercepted and SYNAD will 
be given control when those reads or writes 
are checked. 

Backspace Routine (CZCRG) 

The Backspace routine backspaces a phys- 
ical record on the current magnetic tape or 
direct access volume, (See Chart GO 

Attributes : Reentrant, resident in virtual 
storage, closed routine, nonrecursive, 
privileged. 

Entry Point ; CZCRGA -- Entered by type-lM 
or type-2 linkage. 

Input : Register 1 contains the address of 

the DCB. 

Data References : CHADCB, CHADEB, CHASDA. 

Modules Called : 

Find Records per Track CCZCRQ) -- Find 
records per track. 

Control (CZCRB) — Tape positioning. 

Exits : 

Normal — Return to the calling routine. 

Error — For unsuccessful completion, gen- 
eral register 15 contains a return code 
>f *QH 9 . 

\BEND is called under the following 
conditions: 

• Invalid DCB 

• Unchecked Read or Write outstanding 

• Illegal device or overflow records. 



Operation : For magnetic tape a backspace 
is much easier to perform since only the 
physical position of the tape need be esta- 
blished. On the other hand, the records of 
a sequential data set on DA are not neces- 
sarily packed on the volume, and are not 
necessarily on the same track. They must 
be on the same volume for backspace. 

For a backspace on magnetic tape, the 
Backspace routine links to Control via a 
type-1 linkage, with a backspace record 
request. If a backspace record goes over a 
tape mark, a forward space record command 
is issued to Control, and an error return 
is given to the user. If an unrecoverable 
error occurs, a return code of • 04* is 
placed in general register 15 upon return 
to the user. 

The backspace operation for a direct 
access volume may be very easy or quite 
involved, depending on where (logically) 
the data set is positioned. The DEB con- 
tains the DA address of the next record to 
be processed (DEBNIO). The Read/Write rou- 
tine will operate upon that address when it 
is entered. Consequently, the DA backspace 
is accomplished if the DA address of the 
previous record can be stored into DEBNIO. 
A backspace is not performed on a data set 
which has track overflow specified. Neith- 
er is a backspace performed if the track 
containing the user labels would be 
entered. 

If I/O operations have not been per™ 
formed on the data set, no backspace is 
possible and control is returned to the 
calling routine with a non-zero return 
code. 

Should DEBBP be zero, no prior backspace 
has occurred since the last READ or WRITE. 
And if DEBLIOR contains some positive numb- 
er, there is no possibility of backspacing 
into labels or out of extents. Therefore, 
the backspace is accomplished by moving the 
last I/O address to the next I/O address. 

If a previous backspace operation 
resulted in an error, control is returned 
to the calling routine (return code = 0) 
without any attempt to backspace. The pre- 
vious error will be detected by the Check 
routine when the next I/O operation is 
checked. 

DEBBP is set to 1 when the first backs- 
pace is made. If a previous backspace has 
occurred and current position is not at the 
first record in current track, the backs- 
pace is accomplished by subtracting from 
DEBNIOR which logically positions to the 
* previous record in the current track. 

Note 1 : The Find Records per Track routine 
is used to count the number of records in a 
track. To use it one stores the MBCCHH of 
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interest in DCBRD and calls Find Records 
per Track. When Find Records per Track 
returns, the number of records in the track 
is in DCBRDR. If Find Records per Track is 

called by Backspace and it does not work 
properly, Backspace sets DEBNF1 on so the 
DECS of the next read or write will be 
intercepted by the Read/Write routine and 
Check will transfer to SYNAD. 

Now, if Backspace is entered and 
DEBNIOR=l, the last record of the previous 

track must be found to accomplish the back- 
space. The important thing to determine is 

whether the previous track is just a track 
containing records or if it has the user 
labels. DEBEHT set to one indicates that 
there are labels in the first track of the 
first extent- DEBNIO pointing to the first 
track of the first extent means a backspace 
would leave the extents. DEBNIO pointing 
to the second track of the first extent 
means a backspace will get into the label 
track if there are labels. If the first 
extent is only one track in length, it will 
contain labels if there are labels. When 
DEBNIO is in the first extent and neither 
the first nor the second track is pointed 
to by DEBNIO, then it is safe to backspace 
to the last record on the previous track. 

Note 2 ; The Read/Write routine will per- 
form I/O from the DEBNIO address if DEBBP 
is on, and will then turn DEBBP off. 

DEBBP is turned on by the Backspace rou- 
tine and DEBNH is also turned on if Back- 
space encounters error conditions. It is 
assumed that Read/Write will intercept an 
I/O request to the data set when both the 
above bits are on, and that Check will 
transfer to SYNAD when checking that DECB. 

Control Routine CCZCRB) 

The Control routine performs magnetic 

tape positioning, card reader stacker 
selection and/or printer channel skipping* 
Control builds an IORCB containing appro- 
priate CCWs, and executes it via the IOCAL 
SVC which invokes the I/O Supervisor. (See 
Chart GD.) 

Attributes : Reentrant, resident in virtual 
storage, closed routine, privileged, 
nonr ecursive . 

'Entry Point : CZCRBS — Entered via type-lM 
or type- 2 linkage. 

Input : The following parameters are 

passed: 

Register -- Two-character operation code 
and count modifier. 

Register 1 -- Address of DCB identifying 
I/O device. 



Data References : CHADCB, CHADEB, CHAIOR, 
CHAD EC, CHASDA. 



Modules Called : 

AWAIT CCEAP7) — Await an interruption. 

IOCAL (CEAAC) — I/O call. 

Exits : 

Normal — Return to calling routine. 

Error — 

* Abnormal termination via ABEND macro 
instruction. 

* Exit to SYNAD routine. 

Operation : Initially, the IORCB is 
cleared. Then it is completely filled in 
with the appropriate CCW as well as the 
address of the SAM Posting routine. 

When the IORCB is complete, the IOCAL is 
executed* If the requested operation is 
REW or RUN, control is then returned to the 
calling routine. However, for ail other 
requested operations the DECB is tested to 
determine if the operation is complete* If 
not complete, the AWAIT macro instruction 
is executed to wait for completion of this 
event. When the initiated operation is 
completed f the DECB is tested for error 
indicators . 

Upon successful completion^ control is 
returned to the calling routine. For 
unsuccessful completion, the user's SYNAD 
routine is given control. if there is no 
SYNAD routine and errors exist, the task is 
abnormally terminated. 

ASCII Translation and Conversion Routine 
CCZCWA) / 



Users may read or write physical sequen- 
tial data sets encoded in ASCII with ANS 
(American National Standard) label and 
record formats provided the storage medium 
is magnetic tape. Since TSS/360 processes 
internally in EBCDIC and standard IBM label 
and record formats, this routine is 
required to provide an interface for ASCII 
users. On input, this routine translates 
ASCII to EBCDIC and converts ANS formats to 
the standard IBM formats. On output, it 
translates EBCDIC to ASCII and converts 
standard IBM formats to ANS formats. (See 
Chart GE.) 

Attributes : Reentrant, resident in virtual 
storage, read-only, privileged, 
nonr ecursive. 

Entry Point : CZCWA1 — Entered via type-1 
linkage. 
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Input : Register 1 contains the address of 
a tnree-word parameter list: 

Word 1 - Byte 1 - X'Cl' for output 
X'CS' for input 

Byte 2 - X'OCT (unused) 

Bytes 3 and U - Length of record 
or block 

Word 2 - Address of buffer area 

Word 3 - Address of DCB 



Modules Called: None. 



Exits : 

Normal — 

• Return to caller via BR 14 with return 
code in register 15. 

• On input only, register 1 on return 
will contain the number of bytes 
shifted to overlay any block prefix. 

Error — Return to caller via BR 14 with 
one of the following return codes in 
register 15: 

X*QH* - First byte of parameter list not 
X f Cl f or X'C5* 

X 9 QB* - Buffer offset greater than 99 

Tables and Work Areas : CHADCB, CZCWZA 
(ASCII-to-EBCDIC translation table), CZCWZE 
<EBCDIC-to-ASCII translation table) . 

Operation : On input, after reading a reco- 
rd, where the user has defined his data set 
as ASCII, SAM Posting and Error Retry calls 
this routine to translate the record to 
EBCDIC. On output, before writing a reco- 
rd, BSAM Read/Write calls this routine to 
translate from EBCDIC to ASCII. 



American National Standard record lor- 
mats provide for an optional block prefix 
which may precede the first or only logical 
record in eack block. This prefix may con- 
tain user data and, for format-D (variable- 
length) records, the block length in the 
block descriptor field. The ASCII user, 
entering data sets from tape, may tell the 
system (in either his DDEF command or his 
label) tc expect a block prefix; he may 
specify up to 99 bytes. Any data in the 
block prefix f other than the block length, 
will not be available to him, however. 
ASCII Translation and Conversion saves the 
value (the block length) in the block 
descriptor field (the last four bytes of 
the block prefix) and then shifts the first 
or only record left, overlaying the block 
prefix. The end of the record is zeroed 
out. On output, a user may specify only 
or H bytes of block prefix, and then only 
if format-D records are specified. When a 
a-byte block prefix is specified, it will 
contain a block descriptor. 

The length of the block prefix is speci- 
fied by the buffer offset. The differences 
between American National Standard and 
standard IBM label formats are slight ; one 
difference is the existence of a buffer 
offset field in the second header label 
(American National Standard) . If the user 
specifies or defaults the buffer offset 
(BFOFF) parameter in the DDEF command, the 
buffer offset field in the label determines 
for ASCII Translation and Conversion the 
number of bytes of input block prefix to 
handle. 

The translation and conversion inter- 
faces provided by this routine are illus- 
trated in Figures 10 and 11. 

Additional information on label and 
record formats, both standard IBM and 
American National Standard, for magnetic 
tape volumes is contained in Appendix A of 
Data Management Facilities , GC28-2056. 



ASCII Translation and Conversion 
provides: 

1. A character -for -character translation 
interface between EBCDIC and ASCII. 

2. Conversion of values in block and 
record descriptor fields to unpacked 
decimal (output) or binary (input) 
where records are format-D 
(variable- length) . 

3. On input, evaluation of block or reco- 
rd format and resultant shifting of 
records to overlay any block prefix. 

4. On output, a block prefix of b bytes 
if specified by the user. 



BUFFERING SERVICES 

The following four routines are provided 
to allocate a pool of buffers and permit 
easy access and release of the buffers 
within the pool. 

GETPOOL Routine (CZCMB) 

The GETPOOL (get a buffer pool) routine 
fills the buffer length and the number of 
buffers field in the DCB. (See Chart HA.) 

Attributes ; Reentrant, resident in virtual 
storage, closed routine, read-only, public. 

Entry Point : CZCMBG equated to SYSMBG — 
Entered via type-1 linkage. 
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ON 

INPUT: 



A buffer offset (block prefix length) of 0-99 bytes is supported In all formats. 
The user specifies the buffer offset in either the tape label or the DDEF command. 



FORMAT F records-blocked and unblocked (blocked shown here) 





Data 
(ASCII) 


Data 
(ASCI!) 


Data 
(ASCII) 



is translated to EBCDIC and the BSAM user READs 



Data 
(EBCDIC) 


Data 
(EBCDIC) 


Data 
(EBCDIC) 





the QSAM user GETs. .. 



Data 
(EBCDIC) 



. . , (three times) 



FORMAT U records 



Data (ASCII) 



is translated to EBCDIC and He BSAM user READs. 



Data (EBCDIC) 




the QSAM user GETs.. 



Data (EBCDIC) 



FORMAT D (variable-length) records 



if the buffer offset is specified as 0. . . blocked or 
unblocked (shown)... 



dddd 



Data (ASCII) 



bee 



LL00 


ttoo 


Data (EBCDIC) 



In all Format D cases, whatever the 

buffer offset (0-99)... 

unblocked, 

the BSAM user READs. . . 



If the buffer offset Is specified as 4. . .blocked 
(shown) or unblocked. , . 



jBto&b dddd 



Data (ASCII) 



dddd 



LL00 



£{00 



Data (EBCDIC) 



KD0 



If the buffer offset is specified as other than or 
4, , .blocked or unblocked. . . 




r^ww- 


















Data 




Data 






dddd 




dddd 






PlfilP' ■••'"' 




(ASCII) 




(ASCII) 


««i~ 


mLm 











blocked and unblocked, 
the OSAM user GETs... 



?!00 



Data (EBCDIC) 



LL00 



!C00 



Data 
(EBCDIC) 



etoo 



Data 
(EBCDIC)l 



However, LL00 will exist in the 
system buffer for each Format D 

unblocked record or block. 



Ze roes 
*Does not have to contain DDDD; BSAM calculates and creates correct LL00. 



dddd is the record (length) descriptor in ASCII format; a 4-byte value in unpacked decimal. 

W00 is the record (length) descriptor in EBCDIC format; I ( - a value in binary; 00 = Zeroes (unused). 

DDDD is the block (length) descriptor in ASCI! format; a 4-byte value in unpacked decimal. 

LLOO is the block (length) descriptor in EBCDIC format; LL = a value in binary; 00-= Zeroes (unused). 



Figure 10. How TSS/360 Handles ASCII Record Input 
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ON 

OUTPUT: 



For Formats F and U, no buffer offset (block prefix) is allowed. For Format D, a buffer offset of or 4 may be specified. 



FORMAT F and FORMAT U records - blocked and unblocked 



Data (EBCDIC) 



becomes 



Data (ASCII) 



FORMAT D (variable-length) records - blocked or unblocked 

If a buffer offset of is specified. 



LLOO 


{too 


Data 
(EBCDIC) 


e?oo 


Data 
(EBCDIC) 


becomes. . . 




dddd 


Data 
(ASCII) 


dddd 


Data 
(ASCII) 




If a buffer offset of 4 is specified, the 
EBCDIC block above becomes. . « 




DDDD 


dddd 


Data 
(ASCII) 


dddd 


Data 
(ASCII) 



See Figure 10 for the meaning of dddd, etc. 

Notes: The BSAM user must calculate and supply his own LLOO and #00 and specify buffer offset = 4 if he wants a 
block descriptor on output. 

The QSAM user must specify buffer offset = 4 if he wants a block descriptor even though he does not have 
to supply his own LLOO. 



Figure 11. How TSS/360 Handles ASCII Record Output 



Input : The following parameters are 
passed: 

Register 0: 



Error 



ABEND macro instruction. 



I 



NN 



I 
-J.. 



LL 



15 16 31 

where NN - number of buffers requested. 

LL - length of each buffer in the 
request. 

Register 1 — Address of DCB. 

Data References : CHADCB r CHADEB, CHAISA, 
ChAVPS . 

Kioduies Called : None. 

E xits : 

Normal — Return to caller. 



Operation : The routine will ABEND if the 
DCBID is not valid. The routine also 
ABENDS if a buffer pool has been previously 
assigned, if the buffer length or block 
size exceeds 32,768 bytes, or if the number 
of buffers exceeds 255. GETPOOL inserts 
buffer length and number of buffers into 
DCBBUF and DCBBUN respectively. The rou- 
tine sets on bits corresponding to DCBBUF 
and DCBBUN in DCBMSK if the DCB is open. 

GETBUF Routine (CZCMA) 

The GETBUF (get a buffer) routine finds 
an available buffer in a buffer pool and 
returns a pointer to it- When the GETBUF 
routine is entered for the first time, the 
buffer page list, which describes the loca- 
tion of all the buffers for this DCB, is 
built, the buffer pool is allocated, and 
the first available buffer is obtained. 
(See Chart HB. ) 
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Attributes : Read-only, resident in virtual 
storage, closed routine, reentrant, public. 

Entry Poin t; CZCMAG equated to SY5MAG -- 
tnt«T*'d v l a type-1 iinkaqt^. 

Inpu t: Register 1 contains the address of 
the DCB. 

Data References : CHADCB, CHABPL, CHADEB, 
CHAISA, CHAVPS. 

Modules Called : 

VMA (CZCGA) — Get virtual storage. 

CKCLS (CEAQU) — Check protection class. 

Exits ; 

Normal — Return to calling program. 

Error — ABEND macro instruction. 

Operation : GETBUF will ABEND if the DCBID 
is not valid, or if the DCB is not open. 

If this is the first entry to GETBUF, a 
buffer page list must be built. GETBUF 
ABENDS if the buffer length is too large or 
if buffer length and blocksize are both 
zero. When only buffer length is zero, and 
access is for other than QSAM, and the 
device is direct access, the actual size of 
the buffer is computed by GETBUF by adding 
the key length to the blocksize. GETBUF 
determines which cutoff constant is to be 
used and calculates the total number of 
pages needed for the buffers, and the buff- 
er page list. 

GETMAIN is used to obtain the needed 
pages. GETBUF maintains the count of 
available buffers and enters the buffer 
addresses into the Buffer Page List. 

FREEBUF Routine (CZCNA) 

The FREEBUF (free a buffer) routine 
makes available a buffer which was pre- 
viously obtained and made unavailable by 
the GETBUF routine. (See Chart HC.) 

Attributes : Reentrant, resides in virtual 
storage, closed routine, read-only, public. 

Entry Point : CZCNAF equated to SYSNAF -- 
Entered via type-1 linkage. 

Input : The following parameters are 
passed : 

Register — Address of buffer to be 
released. 

Register 1 — Address of DCB. 

Data References : CHADCB, CHABPL, CHADEB, 
CHAVPS, CHAISA. 



Modules Called: None 

Exits : 

Normal -- Return *o calling program. 

hrroi -- AT.END macro instruction. 

Operatio n: The addressee of buffers in 
CHABPL are searched to find a match for the 
address passed in register 0. When a match 
is found, the In- Use flag for that buffer 
is turned off in the CHABPL, and BPLNBF 
(number of free buffers) is incremented by 
one. 

FREEBUF exits to ABEND if the DCB iden- 
tification is not valid, if GETBUF has not 
been called, if the buffer to be freed is 
not in the pool, or if the buffer to be 
freed is already free. 

FREEPOQL Routine (CZCNB) 

The FREEPOOL (free a buffer pool) rou- 
tine releases all virtual storage which was 
assigned to a DCB as a buffer pool. (See 
Chart HD.) 

Attributes : Reentrant, resident in virtual 
storage, closed routine, read-only, public. 

Entry Point : CZCNBC equated to SYSNBC — 
Entered via type-1 linkage. 

Input : Register 1 contains the address of 
the DCB for the data set which last used 
pool . 



Data References 



CHADCB, CHABPL, CHADEB, 



Free virtual 



CHAVPS, CHAISA, 

Module Called: VMA (CZCGA) 

storage. 

Exits : 

Normal — Return to calling program. 

Error — ABEND macro instruction. 

Oper ation ; FREEPOOL ABENDS if the DCBID is 
not valid, or if the access is QSAM and the 
DCB is open. 

Unless the Buffer Page List pointer is 
zero, the number of pages in the Duffer 
pool is determined from BPLNPG, and FREE- 
MAIN is called to release those pager;. 

FREEPOOL zeros the Buffer Page i.ir.t 
pointer, and the buffer length and nurnter 
of buffers fields in the DCB. 

BSAM INTERNAL CO NTROL ROUTINE S 

The internal control routines include 
the message writing, tape positioning, and 
volume serial field finding routines. 
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Tape Positioning Routine (CZCWP) 

The Tape Positioning routine positions a 
tape volume to any of three positions. The 
positions are shown in Figure 12. (See 
Chart IA. ) 



Attributes ; Reentrant, resides in ritual 
storage, subroutine, privileged. 



Entry Point : CZCWP1 -- Entered via type- 1 
linkage. 

Input : Register 1 contains the address of 
the SAM communication block. SCBPOS con- 
tains the code which indicates which tape 
position is desired. 

Data References : CHADEB, CHASCB, CHASDA, 
CHATDT. 

Modules Called : 

Control (CZCRB) — Tape positioning. 

Message Writer (CZOWM) - — ABEND processing. 

Build DEB (CZCWB) -- Update DEB after 
volume switch. 

Bump CCZCAB) — Mount next volume. 

Volume Sequence Convert (CZCWV) — Deter- 
mine if there is another volume. 

Exits : 

Normal — Return to the calling routine. 

Error — Call Message Writer to do ABEND 
processing. 

Operation : Positioning is always relative 
to the tape marks on a volume. It is 
assumed that unlabeled volumes contain data 
sets separated by single tape marks, and 
that labeled volumes contain data sets with 
a single tape mark separating header labels 
and data, and a single tape mark preceding 
trailer labels. 
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The number of forward or backward spaces 
to be made must first be calculated- The 
calculation is made from the position code, 
the current tape mark count and the logical 
data set sequence number in the JFCB. 

The present position on the tape volume 
is known from the tape mark count which 
indicates how many tape n;arks are behind 
the present position. For example, in 
Figure 13 there are unlabeled data sets on 
a tape volume Cthe current positioning is 
indicated); the tape mark count at this 
position would be two. 

Calculating the Position to Which the Tape 
is to be Moved : A temporary data area, 
TFN, is set to the relative physical 
sequence number of the current data set of 
the current volume. This is calculated by 
subtracting the first logical file (data* 
set) sequence number on the mounted volume 
CTDTLFN - 1) from the logical file sequence 
number CTDTPSQ) of the data set which the 
user requested (TDTFSQ - TDTLFN ♦ 1) „ For 
example, in Figure 13 the TDTFSQ contains a 
2 if this is the only volume, indicating 
that current positioning is somewhere 
within the second data set on the volume, 

It should be noted now that one tape 
mark follows every data set on an unlabeled 
tape volume. Similarly, since there are 
three tape marks associated with each data 
set on labeled tape, multiplying the phys- 
ical sequence number of the current data 
set (TFN) by three, then subtracting one, 
yields the exact number of tape marks pre- 
ceding the first TM of the current data 
set. 

Now that the number of tape marks asso- 
ciated with the data set on which position- 
ing is to occur is known, it only remains 
to determine how many tape marks beyond the 
previous data set are needed to find the 
desired new position in terms of tape 
marks . 

Looking at Figure 12, it is clear that 
for labeled tape: zero additional tape 
marks yields position 1, three additional 
tape marks yields position 2, or two addi- 
tional tape marks yields position 3. For 
unlabeled tape, zero additional tape marks 
yields position one, while one additional 
tape mark yields position 2. Position 3 
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Figure 12. Tape Positions 



* — Pott He 







^_ 






D 


irection of Tape movement 








1 






1 


T 


1 




\ 


T 


1 


""I 




R 




Oafa 


R 


M 


R 


Dah3 


R 


M 


R 1 


Data > 




G 






G 




G 




G 




G 


C 

< 



X_ LOAD POINT ^--{Current position of tape volume) 

Figure 13. Data Positioning 



Section 6: Routines Specifically Designed for BSAM 91 



cannot be found directly now because files 
(tape marks delimit files) are being coun- 
ted in the forward tape direction. A back- 
space file is necessary to obtain position 

3 on nonlabeled tapes after forward space 

files are completed- 

The appropriate number of additional 

tape marks is put into a temporary data 
area TFA« 

Since ail information necessary to find 
the new position is known in terras of tape 
marks* the calculation can be made; 

labeled tape TFS = (TFN-1) x3*TFA 

or 

unlabeled tape TFS = (TFN-D+TFA 

TFS is a temporary data area which con- 
tains the desired new position in terms of 
number of tape marks from the beginning of 
the tape volume. 

The difference between TFS, the desired 
position, and SDATAP f the present position, 
is determined by subtract, ion* The result 
is the number of files (delimited by tape 
marks) to be forward or backward spaced. 
The direction to go is indicated by the 
sign of the above difference. 

The Control routine is used to forward 
or backward space the required number of 
files* 



This procedure is followed until the 
correct file (data set) is reached. 
Then another forward space record is 
done to check for an end-of-tape condi- 
tion. If a tape mark is encountered, a 
check ±:z made for another volume. If 
there is not another volume and the user 
is open for input and reading forward, 
his task is ended via ABEND, Otherwise* 
• the tape is positioned correctly. 

Unlabeled tapes - The same procedure is 
followed as for labeled tapes, except 
only one forward space file is done 
after the forward space record* 

Multivolume Check - If the JFCB indi- 
cat e~ ho th e r volume on an end- of -volume 

condition, it is mounted, the DEB is 
updated, and the tape positioning values 
are updated for the newly- mounted 
volume* In addition* the logical file 
sequence number is placed in the volume 
entry CTDTFSQ) of the TDT. 

Forward motion of the tape can only 
result in position Z or D because spacing 
by files C delimited by tape marks) causes 
the tape to stop in the interrecord gap 
after the skipped file. Therefore, to 
reach the desired position in Figure 14, 
files are skipped forward to reach position 
Z, and then there is a backward skip of one 
file position to the desired position. 



Volume Sequence Convert. Routi ne_ 1CZC/WV > 



The following situation may occur when 
skipping files forward or backward. The 
solution is the same for either case. As 
in Figure 1H there is a requirement for 
forward spacing. 

When forward spacing to the correct 
position, the following procedure is fol- 
lowed if Tape Positioning was called by 
Tape Open: 

Labeled tapes - A forward space record 
is done to check for a tape mark, which 
would indicate the end of the tape. If 

a tape mark is encountered and another 
tape is not specified, an ABEND results. 
If a tape mark is not encountered, three 
forward space files are done to position 
to the beginning of the next' data set. 



The Volume Sequence Convert routine is 
called to determine the address of a volume 
serial field within the correct job file 
control block CJFCB) within the task 
definition table, based on a Relative 
Volume Sequence Number CRVS) stored in the 
SAM communication block CCHASCB). CSee 
Chart IB.) 



Attributes : Reentrant, nonrecursive, resi- 
dent in virtual storage, privileged. 

Entry Point : CZCWV1 — &itered via type-1 
linkage. 

Input : Register 1 contains the address of 
the SAM communication block. 

Data Reference: CHASCB. 
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Figure 14. Skipping Files on Tape 



Modules Called: None. 



Exits: 



Normal -- Register 15 contains one of the 
following return codes: 

•00 s Address of the volume serial 

field requested is in SCBVCA and 
the field is valid. 



92 Part Is Access Method for BSAM, MSAM, TAM and IOREQ 



•0H f SCBVCA contains the address of 
a null volume serial field, or 
a null chain field. 

'08" Volume serial field considered 
out of range. 

Error — None. 

Operation : The calling prograir stores the 
address of a volume serial field within the 
JFCB in the CHASCB, and places a return 
code in general register 15 indicating the 
result of the search. 

The return code setting indicates to the 
calling program whether the volume serial 
field has been located, and if it has, its 
address (stored in CHASCB) . Otherwise, the 
return code indicates whether the RVS 
stored in the CHASCB points to a null 
volume serial field and the address of tnis 
field is stored in the CHASCB; or whether 
the RVS points to a volume serial field 
which would begin the next chain of volume 
serial entries in the JFCB Cin which case 
the CHASCB contains a pointer to the null 
chain field which will be used to point to 
the address of the field requested by the 
RVS). The return code, on the other hand, 
may indicate that the RVS stored in the 
CHASCB points to a volume serial field 
which does not exist in the current JFCB 
Cin which case a pointer to the terminating 
null chain field is stored in the CHASCB) , 
or the return code may indicate that the 
RVS was zero upon entry, and the address of 
the volume serial field pointed to by RVS 
has been set to zero. 

Note ; The first volume serial field in the 
JFCB is assumed to be 1. 

The RVS stored in the CHASCB is not 
changed by VOLCVT. 



Input : Register 1 contains the address of 
CHASCB. The two-byte SCBMSG field of 
CHASCB is set as follows: 



byte 
HAMR0000 



byte 1 
NNNNNNNN 
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Operator message 
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Response required 



and byte I is a message ID consisting of 
a binary number. There is a unique 
number for each message. 

The SCBABN field contains the SAM ABEND 
code, if the call is for an ABEND 
message. 

Data References : CHASCB, CHATDT, CHASDA, 
CHADEB, CHALB1. 

Modules Called : 

WTO (CZABQ) — Write message to operator. 

Gate (CZAAB) — Print message on terminal 
or SYSODT device. 

ABEND (CZACP) — Abnormal termination of a 
task. 



Message Writer Routine (CZCWM ) 

The Message Writer provides for all the 
message handling required by "he SAM Open, 
End- Of -Volume, and Close Routines. This 
module contains all message text. It 
selects the proper method of transmitting 
the message to the user or to the operator. 
Some standard responses are processed and 
returned to the calling SAM modules in the 
form of return codes in general register 
15. 

The Message Writer also handles all 
ABEND processing for BSAM. (See Chart IC. ) 

Attributes : Reentrant, nonrecursive, resi- 
dent in virtual storage, privileged. 

Entry Point : CZCWM1 — Entered via type-1 
linkage. 



Exits : 
Normal 



Return to caller, 



Error — ABEND. 

Operation : This routine uses the message 
code placed in the CHASCB as an index to 
locate the desired entry in the message 
control table (MSGTS). A message is then 
formed in a buffer area in the PSECT of 
this routine. All messages begin with a 
prefix, contain a header if the message is 
for a user, and end with the message text. 

The prefix is built from information in 
the CHASCB. It contains the module name of 
the caller, the abend code, and the message 
code. This uniquely identifies each 
message* 

When the message is for a user, a header 
line is added. This provides the DDNAME 
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and DSNAME to identify the data set being 

processed* 

The phrase or phrases forming the mes- 
sage text are concatenated with the prefix 
and header in the buffer axea* If neces- 
sary, a modification routine is invoked to 
complete variable fields in the text. The 
completed message is then transmitted as 
indicated by flags in the message control 
table* 



e control table flags ind- 
ponse is required, it is 

user by placing a pointer 
buffer in the CHASCB. If 

sponse will be interpreted 
e Get to facilitate testing 
When the expected response 
a retry message is trans- 
same prefix used for the 

Thi^ cycle is then 
he proper reply is obtained. 



The Message Writer routine is called to 
ao ABEND processing when one of the foil ow- 
ing conditions occurs: 

1. Thti message code received from the 
caller indicates an entry outside the 
range of the message control table or 
ao entry within the table that is no 
longer active, 

2. Tim message m too long to be conca- 
tenated in the buffer available. 

3. The modification or response routine 
is not available when indicated. 

4. No SDAT pointer was available when 

required to complete the operator 
message. 

The Messa ge C ontrol T able: The message 
control table contains one entry of two 
words for each message. Each entry , as 
illustrated in Figure 15 # has the following 
format: 



Entry for Single Phoi# Message 



Entry for Multl Phase Message 



LEN Mmmgw Text 



/■ 



LEN Message Text 



LEN Meswge Tex* 



K 



etc , n entries 



UN Message Text 



Figure 15. Entry for Single/Multiple Phase 
Message 



DC A (MSG) | Pointer to message text if PP 
jis 2ero. Pointer to Phrase 
(List of PP entries if PP is not 
| z ero . 

I 

DC s MM f | Code for Modification routine 
1 COO-none) . 

! 

DC *RR" | Code for Response routine 
j C00=none) . 

1 
DC f PP f | Number of entries in Phrase 
(List, 



DC , FF i [Flags, 



H 



1 2 3 H 5 6. 1 



Do not print header. 

i 

Print header. 1XXXXXXX } 

I 
Abend text. X X X X X X X \ 

Prompting Message text. XlXXXXXXf 

Message for User. X X X X X x X 1 

I 
Message for operator . X X 1 X X X X X j 

I 

No response required. XXXOXXXX | 

1 
Response required. XXX1XXXX j 



¥. U }.$ Records per Track _ j^ujt jltu? J C ? e K £) 

The Find Records Per Track routine com- 
putes the number of records on a track of a 
direct access device. For a data set of 
unknown or varying record length, an IORCB 
is set up to read the entire track in order 
to find the number of the last record. 
fSee Chart ID.) 

Entry Point : CZCRQA -- Entered via Type-1 
linkage- 
Inputs Register 1 contains the address of 
the DCB. DCBRDB contains the address of 
the track concerned. 

Modules Called : None. The AWAIT and IOCAL 
SVCS are issued. 

Exits : 

Return Code Condition 



00 
OH 



Normal return. 

I/O error other than 
defective track or *No 
Record Found* . 



Operation : For fixed, standard format 
records, the record count is computed and 
stored in the DCBRDR field* A return to 
the calling routine is then effected* 
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For record formats other than fixed, or 
tixed but not standard, an IORCB is built, 
and an IOCAL issued, which returns the 
record count to a data area in th? PSECT. 
The count is then stored in the DCBRDR 
field of CHADCB. 

This count is also stored in tne DCBRDR 
field if an error return of 'No Record 
Found* is detected after the IOCAL SVC. 

If the IOCAL return shows that the track 
was defective, the alternate Seek address 
is moved into the IORCB and the IOCAL 
issued again. 

Any other error return from ICCAL causes 
Find Records per Track to return a code of 
X'QH* in register 15. 

RELFUL Routine (CZCRR) 

This routine converts a relative direct 
access device address - of the form TTRZ, 
to a full address - of the form RMBBCCHH, 
where R is the record number, M is the 
extent numoer, CC is the cylinder number, 
and HH is the head C track) number. (See 
Chart IE.) 

Entry Point : CZCRRA CSYSRRA eguated) — 
via type-1 linkage. 

Input ; Register 1 contains the address of 
the DCB. DCBRDT contains the relative 
address to be converted. 



Ope ration: The extent number (H) and reco- 
rd number aie moved in t i oih tlu> PEB- The 
track number is computed and it it is on 
the first cylinder ol the extent, the 
cylinder and track (head) are placed 
directly into the DCB and a return to the 
calling modules effected. 

If the track is not on the first cylind- 
er, the cylinder count is updated until the 
track is found, and the cylinder and track 

are computed and stored in the DCB. A 
return to the calling module is effected. 



KULREL Ro ut ine . JC_ZCRS)_ 

FULREL converts a full DA device address 
In the form RMBBCCHH to a relative address 

in the form TTRZ. R is the record number, 
M is the extent number, BB is the bin numb- 
er, CC is the cylinder number, and HH is 

the head (track) number. TTRZ represents 
the relative track and record numbers for 
the current volume. (See Chart IF.) 



Entry Point : CZCRSA (SYSRRA equated) — 
via type-1 linkage. 



Input : Register 1 contains the address of 
the DCB. 



Modules Called: 



None. 



fciodules Called: None. 



Exits: 



Return Code 

00 



04 



Condition 
Normal return - 

Track number is outside 
data set. 



Exits : Return to the calling routine. No 
return code. 

i 
Operation : The address is converted to the 

TTRZ form where the R of TTRZ is set to the 

R of RMBBCCHH minus one, the Z is set to 

zero, and the track is computed by adding 

the number of tracks in the extents. The 

remaining fields of DCBRD are set to zero. 
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PART II 
VIRTUAL ACCESS METHOD (VAM) 



SECTION 1 : 



INTRODUCTION 



The data management facility discussed 
in this section is the virtual access 
method (VAM) - There are three organiza- 
tional methods: virtual sequential, virtu- 
al indexed sequential, and virtual parti- 
tioned, which are designed for use with 
TSS/360. All incoming and outgoing data 
processed by the virtual access methods is 
organized in units of pages which are 4096 
bytes in length and stored on direct access 
devices. 

TSS/360 VAM is designed to minimize the 
number of virtual storage pages associated 
with an open data set. VAM brings into 
virtual storage only those data set pages 
currently needed for user operation. 

In this section, the implementation of 
VAM is presented using seven subdivisions: 

• A general description of VAM including 
its unique characteristics and its spe- 
cial capabilities. 



devices. Each device is pref ormatted, in a 
manner which will he described later, in 
units of f 4096 bytes called pages. Although 
records in a data set may occupy less than 
a page, exactly one page, or more than one 
page, the access method deals in terms of 
page units. 

The general philosophy of the virtual 
access methods is closely tied to the con- 
cept of relocation exceptions. When a user 
issues a request to get or read a record, 
the virtual access method merely adds the 
page or pages containing the record to the 
requesting task's page tables. This opera- 
tion is performed by the Movepage routine 
CCZCOC). That is, the record is read into 
the task's virtual storage. When the task 
in execution makes a reference to the reco- 
rd, a page relocation hardware interruption 
occurs. This interruption causes the resi- 
dent supervisor to read the referenced page 
into main storage by means of its paging 
mechanism. 



• A description of error recovery techni- 
ques used for VAM data sets. 

• A description of the volume format and 
the manner in which data sets are main- 
tained on such a volume. 

• Data set sharing - a detailed discus- 
sion on one of VAM's more important 
facilities. 

• Open and Close processing - that part 
of VAM processing common to all the 
access methods . 

• The virtual sequential access method. 

• The virtual indexed sequential access 
method. 

• The virtual partitioned access method. 

Where practical, individual routines 
will be presented immediately following the 
particular facility they support. The 
first of the above subdivisions, a general 
description of the virtual access methods, 
will occupy the remainder of this section. 



VIRTUAL DATA SET ORGANIZATION 

As metioned above, the data sets 
accessed by the virtual access methods all 
reside on direct access storage devices. 
The devices supported by TSS/360 are the 
2 311 and 2314 direct access disk storage 



A put or write operation, on the other 
hand, results in the actual writing out of 
the record as well as the updating of the 
page tables. The writing operation is per- 
formed by the Movepage routine (CZCOC) 
which issues the PGOUT SVC. This SVC is 
also serviced by the resident supervisor 
and performs the actual writing operation. 

Movepage Routine (CZCOC) 

Movepage is called by OPENVAM (CZCOA) , 
CLOSEVAM (CZCOB), VSAM Get (CZCOR) , VSAM 
Put CCZCOS) , SETL (CZCOT) , FLUSHBUF 
(CZCO^), Getpage (CZCPI), and VISAM Close 
(CZCQA) to perform input or output and to 
control the use of shared pages by setting 
and releasing interlocks. (See Chart JA.) 

Attributes : Read-only, public, privileged. 



Entry Point : CZCOC1 
or type-2 linkage. 



Entered via type-1 



Input : Register 1 contains a pointer to a 
two-word parameter list: 

Word 1 — Address of DCB. 

Word 2 — Address of first page of request. 

Field DCBN contains the relative page 
number of the first data set page of the 
request. 

Field DCBM contains the total number of 
contiguous pages involved in the request. 
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Field DCBOP contains the type of opera- 
tion requested as follows: 

*8 0* Input request. 

"20' Input request with exclusive 
read. 

f i0* Output request. 

•02 f Release read lock. 

•01* Release write lock. 



Modules Called ; 

GETNUMBR (CZCOOl) — Converts the page 
number of a partitioned data set rela- 
tive to a member to the relative page 
number with respect to the start of the 
data set if part of the member has been 
moved to an overflow page. 

Interlock (CZCOH1) — Interlocks the 

external page entry of a shared data 
page or interlocks the entire RESTBL. 



Release Interlock CCZCOI1) — 
above interlocks. 



Releases the 



PGOUT (CEAA1) -- Causes the pages of an 

output request to be written to external 
storage. 

SETXP CCEAH7) — Adds the pages of an input 
request to the task's external page 
table so that the supervisor can bring 
them into main storage when a reference 
to them causes a relocation exception. 

RELEXPG CC2CEN1) — Releases pages assigned 
to the lata set but not in use. 



— Assigns new pages to 



FINDEXPG CCZCEL1) 
the data set. 

Exits : 

Normal — RETURN macro instruction. 



Error — 

1. Return with a code of X'OU" in general 
register 15 if an attempt to perform 
an exclusive read failed because the 
page was already locked. 

2. ABEND is called under the following 
conditions: 

• An unrecoverable error occurs during 
the PGOUT operation. 

• The DCB in the parameter list is not 
the same as the one in the DCB 
header. 

• Illegal data set organization 
exists . 



• An output operation is requested on 
a data set opened for input. This 
is not the case if the output opera- 
tion is to output the POD of a par- 
titioned data set. 

• The request is for input from beyond 
the data set limits. 

• The operation requested is invalid. 

• The DSORG is indexed, and DCBM * 1. 

• An error return is received from 
GETNUMBR. 

• An illegal buffer is passed to Move- 
page for VI organized data sets. 

• The PGOUT buffer is not data or 
overflow. 

Operation : On entry, registers are saved 
and base registers are established in con- 
formance with linkage conventions. If the 
data set is shared, the RESTBL is inter- 
locked. If the address of the DCB is not 
in the DCB header, or if the data set is 
not partitioned and the request is for out- 
put when the DCB was opened for input only, 
a call is made to ABEND. This latter 
operation is valid for partitioned data 
sets since the request may be from CLOSEVAM 
and be a request to write out the POD. 

If the data set is partitioned, the 
relative page number must be determined. 
The user reference is to a relative page 
number based on the start of the member; 
this relative page number must be converted 
to one based on the start of the data set. 
Where part of the member has been relocated 
to an overflow page, GETNUMBR is called to 
make the relative page number determina- 
tion. 

After this calculation or if the data 
set was not partitioned, the request is 
examined further. If the request was for 
an output operation on a partitioned data 
set opened for input, and the request was 
not to output the POD, ABEND is called. If 
this error condition does not exist, pro- 
cessing continues. The extent of the 
requested operation is tested to see if the 
pages involved are all within the limits of 
the pages currently assiqned to the data 
set. If the data set limits will be 
exceeded by the request, ABEND is called. 
If all is in order, the processing con- 
tinues. From this point on, the processing 
differs according to the type of request. 

Output Operation : In general, the output 
of data set pages is accomplished by means 
of the PGOUT SVC. The processing in Move- 
page consists of building a parameter list 
and issuing the SVC. The parameter list 
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for PGOuT contains the first page involved, 
the number of pages, and the virtual 
storage address of the first external page 
entry- The page entries must be converted 
from the format used in the RESTBL (rela 
tive volume number-relative external pa^e 
number) , to a format suitable to the PGGUT 
processor ( symbolic device address-external 
page number) « This conversion is accomp- 
lished by directly indexing into the volume 
table and appending the SDA to the given 
external page number. This parameter is 
then placed in the PGOUT list. This pro- 
cess is repeated, page by page, until all 
pages involved have been placed in the 
parameter list or until the maximum of 8 
entries have been placed in the list. When 
either of these conditions is met, the 
PGOUT SVC is issued and the transfer of 
pages is accomplished. On return from 
PGOUT, the data set is tested to see if it 
is duplexed (see duplexing later in this 
section). If it is, the same parameter 
list is used to write the pages to the 
secondary copy of the data set. When both 
copies have been written out, the procedure 
is repeated, if necessary, for each suc- 
ceeding group of 8 pages until the request 
has been satisfied. 

Once this has been done the exit proce- 
dure is entered- This entails the release 
of RESTBL and page interlocks set on shared 
data set pages and RESTBLs, and a return to 
the calling routine. 



Non-output Operation : Operations which are 
not output may be simple input operations 
on a nonshared data set, input from a 
shared data set, a read exclusive request 
for a shared data set, or a request to 
release a read or write interlock on a 
shared data set page. If none of these 
operations is indicated, a call is made to 
ABEND. 

If the request is for a simple input 
operation on a nonshared data set, the vir- 
tual storage address of the first page in 
the request is computed and placed in the 
parameter list for SETXP. As with the 
parameter list constructed for PGOUT, these 
page entries must be converted to a form 
acceptable to the SETXP processor. The 
conversion process is identical. Page 
entries are converted one by one and placed 
in the parameter list until the list maxi- 
mum of 64 entries is completed or until the 
requested page entries are all in the list. 
The SETXP SVC is then issued. This action 
results in the placement of the pages 
involved in the external page table of the 
task. Any future reference to the pages 
will result in a relocation exception which 
can now be processed by the resident super- 
visor. If there are more than 64 pages 
involved in the requests, this process is 



repeated until all requested pages have 
been placed in the external page table. 

If this input request was not received 
from Open, the number of checked out page^ 
is updated. After that or if the request 
was froir Open, control is returned to the 
calling routine. 

The processing of input requests for 
shared data sets is basically the same as 
for nonshared data sets. The only dif- 
ference is that page level interlocks must 
be set and released in certain operations. 
If the data set organization is other than 
VISAM, no interlocks must be set, so the 
above input processing is entered. The 
parameter list for the SETXP SVC is estab- 
lished and the SVC is issued. If the data 
set is VTSAM but the request is for a di- 
rectory page the same processing occurs. 

When the request is for a data page of a 
VISAM data set, one of two interlocks must 
be set on ail pages involed in the request. 
For data sets opened for input or for 
operations other than read exclusive, a 
read interlock is set on all pages; for a 
read exclusive request, a write interlock 
is set. The significance of these inter- 
locks and the manner in which they are 
imposed is discussed in the section on 
sharing. 

Once the type of interlock has been 
determined, the pages are examined to see 
if an interlock is already set. This 
occurs when an exclusive read request is 
made for a page which is already in use. 
In such a case, a return is made to the 
caller with a return code of • 04 f to indic- 
ate that the page is not currently avail- 
able. If the page is not already locked, a 
call is made to Interlock to impose the 
proper interlock on all pages. This inter- 
lock is not imposed if the call to Movepage 
is for a read request from the dynamic 
loader. Following the setting of appropri- 
ate interlocks, the parameter list is built 
and the SETXP SVC is issued as for non- 
shared input requests. 

After the SVC has been processed and 
control has returned to Movepage, the numb- 
er of pages checked out is updated for all 
requests except those from Open, the RESTBL 
interlock is released and control is 
returned to the calling routine. 

The remaining function performed by 
Movepage is the release of the page level 
interlocks set for input requests on the 
data pages of a VISAM data set. The inter- 
locks set can be either read or write. The 
type of interlock is determined and passed 
to the Release Interlock routine as a para- 
meter. Once the interlocks on the pages 
have been released, the interlock on the 
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RESTBL is released by again calling Release 

Interlock, and control is returned to the 
calling routine. 



THE ACCESS MET HODS 

Associated with 
tional methods is a 
the user may access 
set. These access 
ai sequential acces 
virtual indexed sec 
(VISAM) , and the vi 
method (VPAM) . Thi 
an access method in 
term. VPAM contain 
actual reading or w 
virtual partitioned 
tion of other data 
comb in ed for ease o 
si diary data sets a 
each member is itse 
ai sequential or vi 
data set. It is by 
access methods that 
are actually read i 
storage. 



each of the organize- 

n access method by which 

records in his data 
methods are; the virtu- 
s method (VSAM) , the 
uential access method 
rtual partitioned access 
s last facility is not 

the normal sense of the 
s no routines for the 
riting of records. A 

data set is a coliec- 
sets which a user has 
i" reference. These sub- 
re called members and 
If organized as a virtu- 
rtual indexed sequential 
means of the other 
the records of a member 
nto the task's virtual 



VPAM provides the additional control to 
perform the following functions on members; 

• To create or add to a virtual parti - 
t i oned data set. 

• To prepare any member of a virtual par- 
titioned data set for processing. 

• To add new members to, or delete exist- 
ing members from an existing data set. 

• To update existing members in place* 

The virtual sequential access method 
provides the user with access to records 
that are located in logically sequential 
locations in his virtual storage. Because 
of the nature of the virtual storage con- 
cept, these records may or may not be in 
physically sequential locations in main or 
external storage?, but they may be conceived 
of as being sequentially organized for pro- 
cessing purposes. Tables maintained by the 
data management routines and by the resi- 
dent supervisor make this type of proces- 
sing possible. The manner in which this is 
done is described in detail in the section 
on the virtual sequential access method. 

The virtual sequential access method 

(VSAM) processes virtual sequential data 
sets and virtual sequential members of par- 
titioned data sets. It can be used for any 
of the following functions; 

• To create or extend a virtual sequen- 
tial data set or virtual sequential 
member of a partitioned data set. 



• To delete all records in an existinq 
data set or member, from a specified 
record to the end of the data set . 

• To retrieve the logical records ot the 
data set or member in a sequential 
manner. 

• To update ar existinq record of the 
data set or member in place. 

The virtual indexed sequential access 
method provides the means by which a user 
can access records in a virtual indexed 
sequential data set. Such data sets con- 
tain records which are not sequentially 
located in virtual storage. Each record is 
associated with a key which is contained in 
the record in storage. The lowest record 
key in each data page, except the first 
data page f of a virtual indexed sequential 
data set is also entered in a directory 
which is associated with each such data 
set. By referencing the keys associated 
with the records in a sequential manner, 
the user may process his data set as a 
sequential data set* Optionally he may 
access records in a nonsequential manner , 
selecting the records he wishes in any 
order by referencing the appropriate keys. 
This processing is detailed in the section 
on the virtual indexed sequential access 
method, 

The virtual indexed sequential access 
method (VISAM) processes virtual indexed 
sequential data sets or indexed sequential 
members of partitioned data sets* It can 
be used for any of the following functions; 

• To create a virtual indexed sequential 
data set or member in a sequential 
manner. 

• To retrieve the logical records of the 
data set or member in a sequential or 
nonsequential manner. 

• To update records in a sequential or 
nonsequential manner. 

• To insert records in logical sequence 
within the data set or member. 

• To delete selected records from the 
data set or member. 



FACILITIES PROVIDED BY VAM 

In addition to the restriction that th*!y 
reside only on direct access devices, VAM 
data sets are characterized by two facili- 
ties that they provide for the user. 

The first VAM facility is the sharing jf 
data sets. A user may elect to share his 

data set with other users* When he does 
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this he is known as the data set owner and 
any user who shares the data set with him 
is known as the sharer. The extent to 
which the sharer may use the data set is 
determined by the owner when he permits the 
sharing- He may permit read only access, 
read-write access, or unlimited access. 

The sharing of data sets necessitates 
the use of interlocks which prevent two or 
more users from simultaneously accessing 
the data set. These interlocks and their 
use, as well as the rules for sharing data 
sets and the routines involved in the shar- 
ing process, are discussed in the section 
on sharing. 

The second of these facilities is dup- 
lexing. This facility provides the user 
with an error recovery capability by allow- 
ing him to maintain two identical copies of 
his data set. The user specifies this 
option by opening his data set with the 
DUPOPEN macro instruction rather than with 
the OPEN macro instruction. The net effect 
of this is to link two identical DCBs 
together and to flag his data set RESTBL as 
duplexed. The duplicate copy is updated by 
the Movepage routine as previously 
described and, other than the DUPOPEN macro 
instruction, the user processes his data 
set as he normally would and does not con- 
cern himself with the duplexing operation. 



VAM ERROR RECOVERY TECHNIQUES 

Two routines are used by data management 
to attempt error recovery , or to allow the 
user to make the decision to attempt reco- 
very, rather than cause an ABEND to destroy 
the user's task. 



VMIER Routine (C2CE 1) 

The Virtual Memory Input Error Recovery 
routine is a public, read-only, privileged, 
system routine which is called by the Task 
Monitor to attempt recovery from an input 
error occuiring on a direct access device. 
(See Chart JB. ) 



Entry Point : CZCEI1 - Entered via type-1 
linkage. 



Input : None. The ISA must contain: 

ISAORV — Virtual storage address into 
which the error page was to have been 
read. 

ISAGRE — External page address from which 

the error page was to have been read. 

Modules Called : 

SETXP CCEAH7) — Sets the task's external 
page table to point to the secondary 
copy of a duplexed data set so that a 
good copy of the error page may be 
obtained. 

PGOUT CCEAA1) — Causes the secondary copy 
of the error page to be written to a new 
primary copy location. 

FINDEXPG (CZCEL) -- Assigns a new data page 
to the data set. This page will replace 
the error page and the secondary copy of 
the copy of the error page will be writ- 
ten to it. 

Interlock CCZCOH) — Places an interlock on 
the RESTBL and the external page of a 
shared data set. 



The Virtual Memory Input Error Recovery 
(VMIER) routine is invoked when an error is 
encountered on an input operation taking 
taking place on a direct access device. If 
the user has maintained a duplexed data 
set # the secondary copy is used to replace 
the error page in a newly assigned external 
location of the primary data set # and pro- 
cessing continues. 

The VAM Data Management Error Processing 
(VDMEP) routine is designed to process most 
errors occurring while manipulating data 
sets. The data set in question is closed 
out, appropriate diagnostics are generated, 
and control returned to the user. 

VMIER and VDMEP are not to be confused 
with VMER (Virtual Memory Error Recording) 
and VMSDR {Virtual Memory Statistical Data 
Recording); these modules are called by 
certain access methods posting routines and 
are described in System Service Routines , 
GY28-2018. 



Release Interlock CCZCOI) — ■ Releases the 
aboye interlocks when appropriate. 

WTL CCZABQ) — Writes a message to the sys- 
tem log when a PAT page is in error. 

WTO CCZABQ) • — Informs the operator of a 

successful recovery, 

GATWR CCZATC) — Writes a message to the 
task's SYSOUT when a PAT page of a priv- 
ate volume is in error. 

ABEND CCZACP) — Abnormally terminates a 
task under certain error conditions. 

DSCB/CAT Recovery CCZUFX) -- If the error 
page is in USERCAT or SYSCAT data sets. 

Exits : 

Normal - — Return to the task monitor. 

Error — ABEND is called under the follow- 
ing conditions: 



Section 1: Introduction 103 



• The error occurred on an auxiliary 
paging volume. 

• An unrecoverable error occurred on a 
data page (data set nor duplexed), 

• The device on which the error occurred 
was not a direct access device. 

e The: fn'or t oage Is outside the Limits 

of the device. 

• i\'o ip.^.e>nr:^ external page entry is 
fvA-vS i;; any* open data set* 

• An vj'rc:, page i i". found to fc*e m the 
secondary copy of a duplexed data set. 

© 7h..- fwi'ur ;^qr t s fevna ,l . •*> i«a.t e foe** p. 
:> r i- v „, o ar: 1 ■/ ma, t k ed i n e i r o r . 



-h«' \ hi?' 



f c->*'-th 



*.«Pi"i:; «* pre 



3i*1 seventh 
• .t s t * * u a . . * jg po s s i fol e 
ly functioning supervi- 



s how Id be taken 



mean bad 



y 



arametej 



:.L:' -..'i-.-l^ 1 * : VHVER provides the processing 
*^<c:: e: ^t>'.*^ ihe .v/:, ten* tc avs &*. use of the 
.. »..■.!*;::, i\*: ftdtui'' i :; virtual Digitization 
data sets. Mhen an in pat error occurs on a 
primary data page for such a data set # the 
^'•rrosid^iy copy ef the data page is read and 
rewritten to a newly assignee! primary data 
i-H"i g e 1 oca t , i oi ? i n e r-ct e ma 1 storage. 

snfhen fiinst entered, VMIKR saves the 
input registers and establishes base regis- 
. /rc> for - : :he CS1CT, PSSCT, and SDAT,, It 
r---*t iocis the SDAT by means of the Test 
and Set instruction and locates the SDAT 
• ntry for the device on which the error 
•xcurrfci, If the error occurred on a 
device other than direct access or on an 
auxiliary paging device a call is made to 
ABEND. The same call is made if the error 
page is found to be outside the limits of 
the device. 

The error page is next classified as 
ot •; iig a PAT page f a DSCB page, or a data 
r xge. If it is a PAT page # the page is 
locked and. all the page entries on the page 
are set unavailable for assignment, by set- 
t ing the number of users currently assigned 
to the maximum of 127. This process 
nvolv(*s a call to PGOUT to write out the 
u ..-dated PAT page. Those pages represented 
<y J <-he PAT page in error, are sho%fn 
, ..available for assignment in the SDAT en- 
try tor the device and the PAT page lock is 
released, WTL (CZABQ) is called to make a 
note in the system log concerning the 
error. If the voimse is private a message 
is written to the task's SYSOOT via GATWR 
(CZATC) • After this, or if the volume was 
public, a return is made to the task 
monitor . 



If the error page is not a PAT page, the 
PAT page is locked and the error page is 
examined* If the page is already MirMed in 
error, an attenpt has bMn mad# to road an 
error page and ABEND is called Csince other 
VAM routines, especially OPENVAM f will pre- 
viously have relocated ail known error 
pages) • If this is not the case, the page 
is examined to determine if it is a DSCB 
page or a data page. 

For a DSCB page, the entry in the PAT is 
marked in error and the error page is 
rewritten to its original location. This 
should permit the page to be input correct- 
ly It hat is # without parity errors) on sub- 
sequent references and prevent superfluous 
calls to VW1EB. The resulting data errors 
will be detected via checksum validation by 
those VAM routines which read or write DSCB 
pages that is, VAMOPEM, ADDDS€B # WR1TDSCB # 
CAT¥AM f etc. Both of these operations 
involve calls to the PGO-JT processor. If 
the DSCB page is determined to be for the 
system, catalog data set (SYSCAT) * a call ir. 
»ade to the DSCB/Cataiog Recovery routine 
to rebuild the catalogs the error page is 
riot remitter! to its original location. 
Following this, the SDAT lock is released 
9MQ control is returned to the task 
monitor. 

When the error page, is found to he 

neither PAT nor DSCB, the* chain of JfCBG ip 
the TOT is searched in an attempt to loco*--.* 

the data set which contains the error page. 
This is done by scanning the RESTBLs of all 

open (that is, currently in use) VAM Ion 

direct access) data sets for a match* If 

the entire chain of JFCBs is checked 
without finding a match # ABEND is called 
since this indicates a possible VAM mal- 
function (no page should be input which is 
not part of some VAM data set) . During the 
search all RESTBLs for shared data sets are 
locked while being checked arid unlocked 
afterwards* If the secondary RESTBL is 
located first, the primary RESTBL is used 
to obtain header information needed for the 
scan Cas this information is identical for 
both RESTBLs but is maintained only in the 
primary RESTBL header) . Both primary and 
secondary RESTBLs will eventually be 
searched for the proper external page en- 
try. If the RESTBL fees not contain the 
page, the next JFCB in the chain is retri- 
eved and the search continues. 

Once the error page entry has been 
located in a RESTBL, its entry in the PAT 
is set to indicate the page is in er:or. 
Since recovery is possible only for dup- 
lexed data sets # if the set is nondopiexed, 
a call is made to ABEND. This is also done 
if the data set is duplexed but the error 
occurred on the secondary copy since the 
secondary copy will only be read by VMJER 
when trying to recover from an error to the 
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failing primary copy. Whether duplexed or 
not, the error ^wge is checked to see if it 
is in the USERCAT or SYSCAT data sets; if 
so, a call is made to CZUFX to rebuild the 
catalog and return is made to the task mon- 
itor, if the error page is in the primary 
copy, recovery is possible so the secondary 
copy address is set in the external page 
table via a SETXP call. A call is then 
made to FINDEXPG to assign a new page to 
contain the primary copy, that is, the 
error page replacement in both the RESTBL 
and the DSCB for the data set. When the 
new page has been assiqned, PGOUT is called 
to write the secondary copy to the new pri- 
mary location. Write to Operator is then 
called to inform the operator of a bad page 
on one of the system packs and, incidently, 
that VMIER was invoked successfully; all 
interlocks are then released and a return 
is made to the task monitor* 

VDMEP Routine CCZCQK) 

The VAM Data Management Error Processing 
(VDMEP) routine processes all the errors 
detected while mainipulating a data set- 
VDMEP will close the data set which caused 
the error, release the interlocks set, and 
transmit diagnostic messages to the user's 
SYSOUT. VDMEP is called by the VDMER macro 
expansion or by ABEND CCZACP) . 

If the task is conversational, control 
is returned to the terminal; otherwise the 
task is deleted. (See Chart JC.) 

Entry Points ; 

CZCQK1 — Entered from expansion of the 
VDMER macro. 

CZCQK2 — Entered from CZACP (ABEND) when 
ABEND receives a recursive call while 
processing a VDMEP request. 

CZCQK3 — Entered from CZACP (ABEND) when 
ABEND has successfully completed a VDMEP 
request. 

Input ; 

For entry at CZCgK2 and CZCQK3, there are 
no parameters passed. 

For entry at CZCQK1, register 1 contains 
the address of the following parameter 
list: 

Word 1 — Address of DCB for the data set 
in error. 

word 2 — Pointer to an 8- character Message 
ID, preceded by a 1-byte count of point- 
ers to variable data, and followed by 
the pointers. 



C = l~byte count of pointers. (May be 
zero. ) 

A = 8 character message ID. This doub- 
leword is actually addressed by word 
2 of the parameter list. 

P lf P 2r '—Pn ~ ^-byte pointers to vari- 
able data, if any. 

Word 3 -- Pointer to a 2-byte field; 



Condition 



Byte 1 
■10 • EODAD or SYNAD condition 



r _ T — .—-j. T . 

|C|AAAA|AAAA| P ± V ± P x Pi 
L-J.„„J X 



P 2 P 2 P 2 P. 



I 






•20 s Clear Last Operation flag 

Byte 2 Condition 

' 0A* Called by one of the f OPEN' 

modules - CZCOA r CZCPZ, CZCOP 

•OC 1 SDST error in CZCOA 

•OE' Non-VAM data set in CZCOA 

Modules Called ; 

VAM ABEND Interlock Release (CZCQQI) -- 
Release interlocks. 

FREEMAIN (CZCGA3) -- Free virtual storage. 

FINDJFCB (CZAEB1) — Get JFCB address. 

RELEXPG (CZCEN1) — Release DSCB Slot. 

DELCAT (CZCFD1) — Delete catalog entry. 

Search SDST CCZCQE1) — Close SDST entry. 

Interlock (CZCOH1) — Set RESTBL lock. 

Close Common (CZCLBC) — Close data set. 

Release Interlock (CZCOI1) — Release 
RESTBL lock. 

Disconnect (CZCGA8) — Disconnect from 
shared virtual storage. 

Prompt (CZATJ1) ~ Communicate with user 
terminal. 

Stow (CZCOK1) — - Add or replace VP member. 

XWTO (CZABQ1) — Communicate with the sys~ 

tem operator. 

DUPCLOSE (CZCEZI) -- Close duplexed data 
set. 

CZAWA1 — BULKIO ABEND recovery. 

ABEND (CZACP1) — Abnormal task 

termination. 

ABEND (CZACP3) — Successful VDMEP 
completion. 



Section 1: Introduction 105 



Operation ; This text is keyed to the flow- 
chart for C2CQE CChart JCl and a reference 
by label will foe included for each area.. 

This routine will assemble appropriate dia- 
gnostics to the tiser SYSOOT informing the 

user of the original error which caused the 
.,;<il • :. VPHEP^ toe data set najne of the 
,'i-itri :%.. ; Jo* * nidi th^ error war* detected, 
■j : ■* a 7 : a -. * ! i o :"i * a ke, n on the da t <* s *»i . 

i ; •"• L ^} . * O .-L.AL... ^ I/O.; : :-i : A ^ te A '" *• l * ? riC * a r ^ ^ 2 n * 

. •.' 3/ ^frtorw.1, . cheek will iirar»& rb at ^2 y 

be f'Ci'h- :,■ detco .-;ine ,;. f \h.i..i i T > a i*t'C , ;),i^ -.•.- 

■ >■ '. . '-". i so* the i ecor^i ve cc-uiv is w<c}. '*•- 

. '."e.' v " -c * ;; ; . ! . r * * r ; * t o s t < • r oii f r c/ * » . r » t - r *. : - t .. s .; ; ■ • 

ot . . •' ; <:*;'«•<;-.„ dad the 3 pprvrp-." rt ato V'DFifi 
"•r". v, p^- f\ * -jiJ; .-•;,„ '• ' *' i-:»ir ■:.".} cVilAno . - . . ; 
'» ■ -■. ■■ ,fc "?.- *.','..;■:,», , -,.u.» ,:;,.., ,:, v.iil bo -oo 



Search SDST is called to close the entry 
in the SDST # if the data set is not dup- 
lexed and there are no DCBs open for the 
data set by this task (QK3200 - QK3210) . 



If there are no other DCB headers, 
^ESTBL pointer is cleared (QK122Q - QK 
- QK37G0); but if other DCB headers ex 
:he RESTBL is locked if necessary, and 
existing buffer, overflow and indexed 
sequent i<i i directory f ageb ate frr^.i, 
*E3TBL lock u released .ind the kl MhL 
:onnecttt1 if necessary. If their* >re 
"Jther asers* the RESTht pages aj e iree- 
(QK3300 - QK3570). 



Diagnosi: ic wssoeo- ore output to MoLOo 
a ri i i :i t rhere * r < - n o o | * e n DC B s , h U Kri b . . . f 
Cailsd! COK9I00 - QK9S1Q). 



the 

3570 

ist, 

any 

The 
dis- 



ai: 



c/e. 



For d 



>>; ID 



t h o a f |o: ' o p r i a t e e r ; o .-. 

It Will Ho r.^t «)/. *o. 

I * ''•, :/ * oec.- t ol ? to.oi 
: To .' *irs i o,i . .-O'.Tr . :". v 

* : ** ; , ->., o ;c «d J. .f 1. Oil . I J* „ <t "• 
i. ? ?o:] 3 branch autje 
.■ u* . i n e * V h j. :*; r o u * i n e 
4 j ii r e * I * £ *a ** v: h f? pi c kL, 

h*: speciii^ii xfiiissa^t? 
. t. i- ubj cstt-i % «< 

l^hjilQ} thv: BOTJKIC 



or pr e- 1 og oio" pos 



Jogofi €,.:].].., ABliJNi'C ^ v. required, after 
appropriite processing ?QK00«* - QK0085 - 

QK8500'; , 

0CB1D and XB fteiutf checks are made and 
Either a diagnostic or an information mes- 
sage is inserted in the main Message list 
(QK0100 ~ QX011S) . 

For d zy st em iat<i set, exit io \ r ia 
\}KB500, Otherwise 1 , the special processing 
:.i3g ir; c.e^ied and exit is via the VDHEP 
entry ix^.i nt :.o ABEND, CSACP1!. Ncr'inally ff 
ABEND hnJi t F-tarn to VDMEP at CSCOK3. 

;'o r entry ^,t_C^CQK3 i ABE.^'D ha*: ooinr.pl e ted 
j:irocessIng the VO^SKP requost . VDMF.P R^ist 

i.„o^ operate oi» riie data set in error, En- 
\ -y at CZCCK3 is from ABEND ^ia an entry in 

, '• Al>. Table, 

Processing of unopened data sets is 
shown from (QK30U0 - QK3700) . 

If this is the secondary copy of a dup- 
lexed data set # the primary copy is found 
and closed CQK30H1 - QK30H4) • 

If a new data set was being created, the 
DSCB slot and catalog entry are deleted 
CQK3055 - QK3100). 



Vr- ..e.s:,inq, of o per. '•:••] d^ici se v ' \:.i •., f .>c 
in :^i« rt JC '.lK3 < »00 - iy^klCn)), 

^ W tVAFtiO -:.*;t..T iocK Pf^.eai's' is cci'!.. :. to 

release i »i 4 or io^::ks , and xi no oPGW 03 
necessaiy or »*1 lowed, the data set is 
closed with either CLOSE or -X^-Clr >?/*:, ?«;•; 
•.., h a me-ii ••■• a g e/ e^t it pha s e c £ the 1 o u t i i r- i . , 
filtered (QK3900 - QK«G50 - 0KU5OC ■• ^.^70.. 
- QK9100 5 * 

If a STOW is necessary j a f.-TCW-.*-: is done- 
■/A an old ©ember CQK^OSO) and a STOW-N done 
00 a T' t ev snemirer - ot on th/.- ol :J 'flnesaber if 

The STOW-R didn't -.-ike o'v?o«K^ - QK435C . 

1 1 the ta s k I s :,? on ve r sa t i or»a i zhe u ; • e r 
is prompted ; ? >#t the member narce CQK^250 - 
OK4 270) . 



if tbe user has had 
defaults or if the tas 
al tf a unique member na 
¥»!EP asd placed in a 
■user of tlie naioe. Thi 
name will consist of <* 
ters and </ nuitieric cha 
initially *mmm 9 = 000 
from CZCOK CS*B3W> indi 
er naaie already exists 
me o ted b'y 1 and the ca 



: oar PftMPTs or 
k is non coftver sat: ion-** 
me is created by 
message to i of or m the 
s 8 character member 

alphabetic char a c- 
racters; •AAAANNNN 1 „ 
0; if a return code 
cates that this toero 
, 9 mmi* is incre- 
11 to STOW issued 



tfhen > he STOW-N 3 s t.;onsipl8te, * he <ny*m^ez 
name is written in SY.SLOG fo: .3 rscru:'irr^>\«:- 
sational task i^K^'i :>'..•> , and both conve: '*,* 
tional and nonconver national tasks CLOSE/ 

DUPCLOSE the data set and enter the 

mess age/ exit phase of the routine (CKUbOO ~ 

QK9100) . 

There is a subroutine (also used In- 
line) which places the diagnostic/message 
and its inserts in the message list (QK905G 

- QK909OK 

Any messages for SYSOOT that can be 
written CSYSOUT f SYSMLF are open - PROMPT 
can be called) are passed via CZATJ (QK9100 
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- QK9150), and then written in SYSLOG via 
CZABQ (QK9200 - QK9250) . 

ABEND is called if required at CZACP1, 
returned to normally if a previous call to 
CZACP3 was made from VDMEP, or called at 
CZACP3 if no previous call occurred CQK9500 

- QK9600). 

For entry at CZCQK2 : CZCQK2 is entered 
from ABEND, when ABEND receives a recursive 
call while processing a VDMEP request. The 
'ABEND Required" switch is set and the 

message/exit phase entered. 



VAM INTERFACES 

VAM effects the input/output of data by 
interfacing with the paging supervisor. 
External storage of a VAM data set is 
limited to direct access devices, whose 
records are in the page (4096 bytes) format 
used with that device, 

VAM data sets are organized by relative 
page number. Each page of a data set is 
assigned a page number which is relative to 
the beginning of the data set. 

These relative page numbers are trans- 
lated to an input/output device address 
through use of the relative external 
storage correspondence table (RESTED . The 
content of the RESTBL is created from data 
set extents obtained from data set control 
blocks (DSCBs) and maintained within virtu- 
al storage by VAM routines. External 
device addresses supplied by the RESTBL are 
passed to the paging supervisor, as 
required, to build the external page 
tables. In part, these are pointers to 
external storage areas associated with the 
active pages of a VAM data set. 

One or more pages are required for the 
RESTBL. If a partitioned organization data 
set is opened , the partitioned organization 
directory (POD) will reside in virtual 
storage. For an index sequential data set, 
directory pageCs) , plus possibly an over- 
flow page, will exist in virtual storage in 
addition to a one- page data buffer. With 
VSAM, a buffer in virtual storage is pro- 
vided which is large enough to contain the 
largest record in the user's data set, with 
a maximum size of one segment (256 pages). 

VAM is designed to minimize the number 
of virtual storage pages associated with an 
open data set. Only those data set pages 
currently being operated on by the user's 
program are addressable as virtual storage. 

The virtual access methods routines 
interface with other routines in TSS/360 
including some in the command system, cata- 
log services, and the resident supervisor. 



These external routines are referenced in 
the module descriptions of the access 
methods routines. 



MODULE ATTRIBUTES 

All modules of the VAM have the follow- 
ing attributes: 



READ-ONLY 



REENTERABLE 



PRIVILEGED 



The storage protection key 
is set to prevent the user 
from performing a store 
operation on any part of 
the CSECT. 

More than one task may 
concurrently execute the 
code embodied in the 

CSECT. 

The CSECT will be pro- 
tected against any 
reference by nonprivileged 
routines: the CSECT, 
however, may reference any 
part of VM. 

Available to all tasks. 

The size assigned will not 
vary while in execution. 

User reference to the 
module is prohibited, 
except through SYS sym- 
bols. SYS symbols are 
used to label entry points 
to nonprivileged system 
routines to which the user 
may transfer control by a 
standard CALL linkage. 



LINKAGE CONVENTIONS 

f 

Seven modules of VAA are considered 
"fence sitters** That is, they may be 
called via type-1 linkage by either a pri- 
vileged or a nonprivileged routine. Calls 
from those modules to privileged modules 
will be type- 2 if it is necessary to "cross 
the fence." 

The "fence sitters* are: 



PUBLIC 
FIXED 

SYSTEM 



GET CZCOR 

PUT CZCOS 

SETL CZCOT 

PUTX CZCOU 

GET CZCPA 

PUT CZCPB 

SETL CZCPC 



VSAM routines 



VISAM routines 



The routines referenced by the above 
modules may sometimes be called by type- 2 
linkage. In order to effect type-2 link- 
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age, V-cons and R-cons for the following 
modules are stored in the enter table 
(CHBET1). The code to access those modules 
in a 1 so g i ven . 



Name 



j„. 



I Entry Point | ENTER Code 



MOV EP AGE | 


czcoci ! 


x s 4C 


i 

INS PAGE | 


1 

CZCODl. | 

i 


X - «*8 f 


1 
DEL PAGE 1 

i 


I 
CZCOD2 S 

1 


X*49 f 


1 

POT j 

t 


1 
CZCOS3 1 

i 


X 1 3E f 


1 
FLUSHBUF j 


1 
CZCOV1 J 

I 


x tt aD f 


1 

6ETPA6B | 

! 


i ! 
CZCPI1 I 

1 CZCPJ2 1 

{ CZCPI3 « 


x*a7 f 

X s 4E f 

x f aF f 


1 ! 
ADE j CZCPL1 j 


X - il6 f 



Other VAM modules may be called by eith- 
er privileged or nonprivileged routines but 
are always executed in the privileged 
state. Those modules are also listed in 
the enter tables 



Table 24 . Abbreviations Used in Control 
Block Descriptions 



Address of an area-control block* 
subroutine, etc. 

Relative Dyte position within an 
area* 



EBCDIC data. 

Relative doubieword within a 
control block. 

Lock byte to be referenced by Test 
and Set (TS) instruction* See 
INTJJC CCZCOH) module description 
for more information. 

Number -- count, limit, size, etc. 

R»con — address of a PS ITT . 

V-con -- address of an entry point 
to a CSECT. 

Relative word position within a 
cont ro i bl oc k * 

Code defined in hexadecimal, or a 
group of fields* 






S Pane S Entry Point | BOTER Code j 



I FIND 

I 



| CZCOJ1 i 



I STOW 
i 



| CZCOK1 

1 

ESETL j CZCPD1 

I i 

S READ/WRITE | CZCPE1 

! I 

| RELEX | CZCPG1 

1 I 

1 DELREC | CZCPHi 



I 



•45 1 

f 42' 



-™H 



Control Mock descriptions in this PLM 
provide the following information to assist 
in the understanding of the Virtual Access 

Method, 

« SYMBOL - The assembly mnemonic as it 
appears in the assembly listing 9 DSECT 
listing, or module descriptions in this 
manual. 

• DATA - A code to indicate the format of 
the information stored in a field* The 

possible values are listed in Table 24 . 



• DESCRIPTION - A brief description of 
the contents and usage of a field. Fgi 
code fields f a list of possible vaues 
is also given* 

Control blocks and tables common to all 
VAM access methods are described in this 
section. Elements which are used only by a 
single VAM access method Csuch as V1SAM) 
are presented with the discussion of the 
appropriate routine • 



Interruption Storage Area tISh) — (CUAISA) 

The interruption storage area is locatec 
at virtual storage addresses through 
4095. One copy exists for each task* It 
is used as a fixed communication region for 
interruption processing between the task 
and the task monitor , and between the task 
and the resident supervisor C Table 25) . 

Task _D a t. a_ Del ia.it ion T --ijble, JTD T) _ - ~ 

CCHATDT) 



The TDT specifies the data set name, and 
supplies information about the external 
storage of the data set. This control 
block is generated pzior to OPEN time by 
either a DDEF command or a DDEF macro 
instruction. It is updated at open time if 
necessary (Table 26). 
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Table 25. Selected Fields of the Interrupt 
Storage Area 



(Symbol | Data | 



J™ 



~+— 



Description 



I 



ISAVMP 


A | 


ISANAS 


N J 


JSATDT* 


A 1 


ISASPN 


N | 


ISATDY 


A | 


ISASDS* 


A | 


ISAVTB 


X | 


ISALCK* 


i I* 1 


ISACVP 


X | 



Virtual storage tacking 
origin 

Next available segment 

Task Data Definition Table 
origin 

Shared Page Table number of 
the public segment 

Dynamic Loader Task 
Dictionary 

Shared Data Set Table CSDST) 

Authority code 

Task Interruption Inhibit 
lock byte 



Current VPSW 

H — „„A__-i„„ ..... 

|*Used directly by VAM. 

i__. . .„ ... — 



. „„ H 



Data Control Block (DCS - CHADCB) : (Figure 
16 and Tables 27, 28 , 34, and 35), 

The data control block, generated by a 
DCB macro instruction, is used to maintain 
information necessary for access method 
routines to process a data set. It con- 
tains data set organization, record format 9 
current page number, last operation, retri- 
eval address of the current record, and 
V-cons and R-cons of the access method rou- 
tines Cmacro transfer list) to process the 
data set or member « 

A DCB is generated at assembly time by 
the DCB macro instruction. Subsequently, 
both the programmer and the system may 
enter information into the data control 
block fields. The process of filling in 
the DCB is completed at execution time* 

Sources of information for DCB fields 
are, the DCB macro instruction in the 
source program, the DDEF coirsmand or macro 
instruction in the job stream Cor DDEF 
macro instruction executed by the user pro- 
gram) , and the DSCB* 

These sources are used in that order and 
only fields not yet specified can be filled 
from each source* For example, if a field 
is specified in both the DDEF command or 
macro instruction and the DSCB, only infor- 
mation supplied by the DDEF command or 
macro instruction is used for the DCB; the 



Table 26. Selected Fields of a JFCB 

r _ T T — _ — . 

| Symbol | Data | Description 



TDTDDN | C 

I 

TDTDS1, j C 

TDTDS2 j 

TDTDSV I X 



TDTDSR | 


C 


TDTDSM | 


c 


TDTOPN | 


N 


TDTVPY | 


X 


TDTAQL | 


X 



TDTSHC 



TDTDEB 


A 


TDTDCB 


X 


TDTVF1 


X 


TDTID1 


c 


TDTDSC 


A 


TDTDUP 


A 


TDTSD1 


» A 


TDTID2 


X 



i 



1 TDTAPN 

I 

ITDTAPP 



X 
A 



DDEF name (ddname) | 

Data Set name j 

Data Set Organization j 

X'Ot* 8 VI SAM | 

X'OS 1 VSAM j 

X 8 06 f VPAM j 

Absolute generation number | 

Member name j 

Number of open DCBs ] 

Privilege flag; X^Ol* = \ 

privileged f 

Access Qualifier \ 

X f 00' unlimited \ 

X f 01' read/write | 

X , 02 f read only | 

} 
Sharing qualifier; X s 01 • = 5 
shared f 

I 
Pointer to RESTBL ( 

I 
First 32 bytes of DCB | 

i 

Volume flag | 

I 
Volume serial number | 

1 
Pointer to format E DSCB | 

I 
Pointer to secondary JFCB of J 

a duplexed set \ 

i 

Symbolic Device Allocation | 
table CSDAT pointer) j 

I 
2nd and 3rd volumes; same I 
format as for TDTVF1, % 
TDTID1, and TDTSDI f above j 

I 
Chain flag ( 

I 
Chain to JFCB appendage | 



corresponding field in the DSCB is ignored* 
The programmer can write routines that 
modify any data control block field. 

The DCB for VAM is composed of five 
parts. The first part of the DCB is common 
to all access methods* The four remaining 
parts pertain to VAM only- Their relation- 
ship is shown in Figure 16. 
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120 
bytes 



h- 



32 

bytes 



(CHADCS) 

DC& Corrwnon 
Used by oil access method* 



Transfer List for Macros 
Common to all VAM Orgonizotl< 



Organization Independent 
Work ing Storage 



T 



Cxtended Sequenflof 
Working Storage 



Extended Indexed 
Sequential Working 
Storage 



Figure 16. DCB Format for VAM 



-_L- 



Table 27, 



Selected Fields of the DCB 
Common 



28 

bytes 



R e i a :.. i. v e Extern a i_ St ora q e Co n: esp on deuce 
.fiM^£IlMSTBL)_ 

A control block used exclusively by VAM 
is the relative external storage correspon- 
dence table (RESTED. A RESTBL is asso- 
ciated with each open data set using the 
virtual access method. It contains a list 
of external pages assigned to the data set* 
The RESTBL is used to convert page numbers 
relative to the data set, to external 
storage addresses. It also maintains con- 
trol over data set page sharing. The 
RESTBL is located in an area of virtual 
storage protected from the user* The area 
of virtual storage that contains the RESTBL 
has a read-only protection key assigned. 
In the case of a shareable data set, the 
RESTBL pages are shared by user tasks , VAM 
sharing rules are discussed in the section 
on sharing. 

A RESTBL is composed of four subsections 
whose functions are described below* The 
overall relationship is shown in Figure 17. 

The RESTBL header contains control 
information for using the RESTBL* 

The second subsection, (Figure 18), con- 
sists of a series of external page entries 
(EPE) r with the control block identifica- 
tion CHAEPE. 

One entry exists for each page of the 
data set, and contains the relative volume 
number and relative external page number, 
plus the page status, defined as in use, 
not in use, or assigned but not yet 
written. 



| Symbol | Data | 



Description 



H „„„ H 

(DCBDSO ■ 


X 


_, 


>„„„„„. _. — —„„_„j 

Data Set Organization j 

Macro j 

Code Param Access Routines | 


| DCBDVl 
| DCBDV2 
| DCBDV3 
| DCBDV4 
| DCBDVS 


X f 71' VIS VISAM | 
X f 72 ! VS VSAM | 
X'73 f VIP VISAM & VPAM | 
X f 74 f VSP VSAM ( VPAM | 
X'75 f VP VPAM € * | 








♦As determined by member | 
organization j 


| DCBDDN 


C 




DDEF nan.e (ddname) j 


JDCBSYV, 
IDCBSYR 


v # 


R 


Synchronous Error exit j 
address tSYNAD) ] 


IDCBEOV, 
| DCBEOR 


v # 


R 


End of Data exit address j 
CEO DAD) | 


| DCBREC 

| DCBRCF 
| DC BRCV 
j DCBRCU 


X 




Record forrr.at j 
X*80 f Fixed | 
X* W Variable j 

i X f C0* Undefined | 


1 DCBLRE 


N 




(Record length j 


jDCBKEY 


N 




Key length } 


fDCBRKP 


N 




1 Relative key position | 


IDCBLPA 


N 




Retrieval address J 


|DCBEXl f 

|DCBEX2 


X 




SYNAD codes j 


(DCBOPI 


, X 




,OPEN options j 


(DCBID 


c 




DCB identifier: c'*%+% 9 j 


j DCBDEB 


A 




Pointer to RESTBL | 


| DCBLEN 


| N 




| Length of this DCB I in j 
| doubleword s ) j 


IDCBGTV, 

| DCBGTR 


! v. 


R 


|GET routine* j 


jDCBPTV, 
| DCBPTR 


! v. 


R 


jPUT routine* | 


|DCBPXV, 
fDCBPXR 


- v, 


R 


: PUTX routine* | 


|DCBSLV, 
JDCBSLR 


1 v, 

L - 


R 


;SETX routine* j 
t _ . „ — _„— ._ — .__„ — —f 


1 

|*R-cons 

j dynamic 


sail 


P< 

-y 


winter to save areas on a j 
allocated page j 
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Table 28, Description of the Fields Com- 
prising the VAM Organization 
Independent Working Storage 



r 



| Symbol | Data | 
j. + + . 



DCBVMA 


A 


DCBCPB 


N 


BCBDPN 


N 


DCBCBP 


N 


DCBN 


N 


DCBM 


N 


DCBOP 


X 


DCBOPO 




DCBOP1 




DCBOP2 




DCBOP3 




DCBOP 4 




DC BOPS 




DCB0P6 




DCBOP7 




DCBOP 8 





iDCBHV 



IDCBNI 



[DCBSHC 



[ DCBHD 1 A 



Description j 

. „_ „„„_ 4 

| VMA of next record in buffer] 

[Current paqe and byte; 
(defined as follows: 

| Current data page number 

I Byte position relative to 
[current paqe 

|First page in request 

| Number of requested pages 

|VAM General Services 

(Operation: 

| X' 8000* Input, set Read 
| interlock 

IX'^OOO' Loader request 

IX^OOO* Input, set Write 
interlock 

|X f 1000 f Output 

IX'0800' Insert 

IX'^OO' Delete 

| X' 0200' Release Read 
| interlock 

IX'OIOO' Release Write 
interlock 

[X'OQSO* Replace blank pages 
| on an insert 

[Hash value of member name (6 1 
i bits) 

First page in request, 
[relative to data set - 
[computed by VPAM routine 
[GETNUMBR (CZCOO) 

(Type of search request? see 
: SEARCH (C2COL) 

|C S A' Alias name 

|C*E S Either alias or member 
[ name 

IC'K' Member name 

DCB header in RESTBL 



_. JL- . — 



._ — __j 



Max imum 

size Is 

262, 144 

bytes 



1 . 

Figure 17. 



RESTBL Header 
(CHARHD) 



External 

Page Entries 
(CHAEPE) 



Available Space 

(ZERO bytes) 



DCB and Member 

Headers 

{CHADHD 3* CHAMHD) 



RESTBL Fcrmat 



1 








A b 






f-"» 






y es 






Flag 


Relative Volume Number 


External Page Number 






2 






| 






i~" 








]"* 







Figure II 



RESTBL External Page Entry 
CHAEPE 



For shared data sets, a 4-byte interlock 
word in each EPE controls sharing of the 
page. The interlock control word, and 
method of updating it, is discussed in 
detail in the sections on VAM sharing. 

The third and fourth subsections of the 

RESTBL,/ designated as DCB and member head- 
ers (CHADED and CHAMHD) , are constructed at 

open time. Address pointers in the DCB 
header identify associated control blocks; 
DCB # JFCB f POD, RESTBL header. The DCB 
header is linked to the RESTBL header or 
the member header C if partitioned organiza- 
tion) oy DHDLNK. 

The DCB header link, and compatible 
field design of the RESTBL and member head- 
ers, make it possible to process members of 
data sets identically. 

A RESTBL is created for a data set by 
the OP EN VAM CCZCOA) routine, using informa- 
tion extracted from the DSCP.s of the 
volumes where the data set resides. Each 
volume contains all data set control blocks 
(DSCBs) for the data sets contained on that 
volume. At open time, the external page 
entries CEPE) are built from extents found 
in the DSCB. As the data set is generated, 
additional extents are obtained dynamically 
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by REQPAGE (CZCOE) . Once a shared data set 
is open* no new RESTBL is generated by any 
subsequent GWm* that is, only one RESTBL 
ever exists at a time for a shared data 
set. However, for each DCB opened for a 
data set, one DCB header will exist in the 
RESTBL. If this is a shared, nonparti- 
tioned data set, each user's DCB will have 
a DCB header. Each of these headers t in 
turn, is linked to the RESTBL header. 

For a partitioned data set, the DCB 
headers of each open DCB will be linked to 
member headers. 

The basic purpose of the RESTBL header 
or member header is to document three items 
of importance: 

• ORGANIZATION - Sequential or Index 
Sequential 

• RECORD FORMAT - Fixed, Variable or 
Undefined 

• CONTENT - Starting page position in the 
RESTBL, number of data, overflow, or 
directory pages 

The RESTBL header also accounts for 
pages assigned to the data set, but not yet 
in use, as well as available virtual 
storage in the RESTBL, 

Closing a DCB causes its DCB header to 
£>e deleted from the RESTBL. In a parti- 
tioned data set, this also causes the memb- 
er header to be deleted provided no other 
DCB headers exist for that member. The 
RESTBL header and external page entries 
will remain in virtual storage until the 
last DCB is closed. At that time, the CLO- 
SEVAM CCZCOB) routine will return the con- 
tents of the RESTBL to the DSCBs associated 
with the data set. 

Descriptions of fields for the RESTBL 
header CCHARHD) and for the DCB header 

(CHADHD) are provided in Table 29 and Table 

30, respectively* 

Shared Data Set Table CSDST) 



The SDST, whose address is given in the 
interruption storage area CCHAISA) of each 
task, consists of a header (CHASDS) and a 
series of data set CCHASDE) and member 
1CHA5DM) entries. The SDST format is illu- 
strated in Figure 19. Tables 31, 32, and 
33 provide field descriptions of the SDST 
header, a member entry and a data set en- 
try. The data set entries are linked by 
forward and backward chain pointers, with 
the pointer to the first data set entry in 
the SDST header. Member entries are 
organized into 6 4 hash chains. The hash 
chain to which a member is linked is 
generated from the member name. A table of 



64 words, part of the SDST header, gives 

the address of the first member within each 
hash chain. In addition to the data set 
and member chains, two chains of deleted 
entries are maintained In order to recover 

space for building data set or member 
entries. Data set and member entries are 
linked to the appropriate deleted chain 
when their user count teaches zero. 

The information in the data set and 
member entries is used to control access to 
a data set, and also to provide a common 
location to store the information C shared 
page table number and RESTBL address) 
necessary for multiple tasks to obtain 
access to an existing control block in 
shared virtual storage. This control block 
is updated by the VAM general services rou- 
tine Search SDST CCZCQE) which has the fol- 
lowing capabilities: 

• Search the SDST for a specified data 
set entry and/or member entry. 

• Modify data set or member entries by 
incrementing or decrementing the user 
count. This capability also provides 
for creating or deleting such entries. 

The linkages between a user's DCB and 
the RESTBL, POD, and JFCB for a member of a 
partitioned data set, are shown in Figure 
20. DHDLNK is shown as linked to either a 
member header or the RESTBL header, since 
this field, when the data set is non- 
partitioned, will point to the RESTBL head- 
er. If this data set were shareable, the 
RESTBL and POD would be in shared virtual 
storage. 



SDST MAINTENANCE 

The following routine maintains the 

shared data set table CSDST). 

Search SDST Routine CCZCQE) 

The Search Shared Data Set Table routine 

is called by OPENVAM CCZCOA), CLOSEVAM 
CCZCOB), Find CCZCOJ), Stow CCZCOK) , and 
the dynamic loader, to add, update or 
delete, data set or member entries in the 
shared data set table (SDST) , and establish 
correspondence to shared virtual storage* 
(See Chart JD. ) 

Entry Point ; CZCQE1 - Entered via type-1 
linkage. 

Input ; Register 1 contains the address of 
a four-word parameter lists 

Word 1 — Address of JFCB. 

Word 2 — Address of DCB. 
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Table 29. Field Descriptions for the RESTBL 

. . . 1 

Description | 



r — T r - 

| Symbol | Data | 



h 



-4 



The first 4 bytes of the 
RESTBL form a VAM interlock 
word which is updated by 
INTLK (CZCOH) and RLINTLK 
(CZCOI) 

RHD1NW I L (Write interlock 

RHDINR | N (Read interlock 

RHDINN | N [Count of read interlocks set 

RHDINI | L (Update interlock 

RHDNAP | W (Next available External Page 
Entry CEPE) 

RHDNEP | N (Count of available EPE 

RHDFEP 1 W I First EPE of data set 

RHDDIR | N (Size (pages) of the Indexed 
Sequential Directory or 
Partitioned Organization 
Directory (POD) 

Data set size (pages) 

Number of overflow pages 

RESTBL size (pages) 

Last header built from 
available space. This 
field, when decremented by 
the size of the header to be 
built (DCB=48, member=32) 
gives the address where a 
new header may be built 

RHDFLG | X | Data set organizations 
X^O" Shared 
X'UO* Partitioned 
X^O* Index Sequential 
X f 08 f ISD Integrity 
X'OU* POD Integrity 
X"02 - DSCB Integrity 
X'Ol 1 Recatalog Flag 



RHDDAT 


N 


RHDOVF 


, n 


RHDRPG 


■ n 


RHDTHD 


| w 



Header — 


(CHARHD) 


r „. 1 T 

(Symbol |Data| 

L—..__ x -i 


. . .. , — 1 

Description \ 

Lock byte for the next 6 j 
fields J 


r T 

[RHDrNI | 


— T 

L | 


1RHDDCB | 


N ] 


Number of DCBs that are OPEN| 


1RHDODC | 


D | 


First DCB header j 


|RHDADC 


D 


First deleted (available) j 
DCB header space j 


| RHDOMC 1 


D | 


First member header j 


| RHDAMC 


D | 


First deleted (available) j 
member header space j 


|RHDPOD 


A 


POD i 


(RHDTID 


D 


Task ID which set RESTBL | 
interlock j 


| RHDVT A 


A 


Address of the volume table j 


1 RHDSPT 


X 


Pointer to the format E DSCB) 


1RHDCPO 


N 


Data set cumulative pageout | 
count | 


|RHDSAL 


1 A 


Secondary allocation (ESA) j 


1RHDRFM 


\ X 


| Record format | 


IRHDKYL 


1 x 


[Key length j 


|RHDPAD 


I x 


|VI pad factor j 


IRHDRKP 


1 B 


| Relative key position | 


| RHDRCL 


| N 


[Record length j 


| RHDDSO 


1 x 


| DSORG | 


(RHDCRD 


| X 


| Change/Reference Date flags j 


| RHDOPC 


1 X 


| Option codes j 

JL . . . . -. J 
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Table 30. Field Descriptions for the DCB 

Header -- (CHADHD) (Part 1 of 2) 



Table 30. Field Descriptions for the DCB 
Header « CCHADHD) (Part 2 of 2 



JSymDol | Data | 



h 



Description 



DHDDCB 


I A 


DHBJFC 


; a 


DHDTSK 


I N 


DHDRES 


A 


DHDPOD 


i A 


DHDLNK 


': h 



DriDOPN 



DHDPRO 



DHDINT 



IiXTjJ associated with this 
| header 



i 



JFCH CTDT> for the data set 

Task identification 

RESTBL address 

POD address 

Linkage to either the RESTBL 
header or to the member 

header if this is a 
partitioned data set and a 
member is active (FIND has 
been done) 



OPEN options 
DCBOP1 



same as 



Protection class of the 
virtual storage in which the 

DCB resides 

X f 03 8 Read only 

X s 01 s Read/Write 

X*07 s private privileged 

Interlock summary. This 
field is updated by INTLK 
CCZCOH), RLINTLK (CZC01) , 
and VAMABIR (CZCQQ) 

The following reflect 
interlocks set in the 
indicated control blocks: 



X'OOQl' 

X' 0002* 

x f oooa* 

X'0008' 
X" 0010' 

X e 0020 i 

x'ooao' 

X'0080' 



X'OIOO - 



Data Set Entry in 

SDST 

RESTBL header 

Member descriptor in 

POD 

POD 

EPF that are checked 

out to this DCB 

Member heaaer in 

RESTBL 

SDST control entry 

RESTBL header 

partial interlock 

set (RHDINI) 

SPT number in SDST 

Data Set Entry 

locked 



Some of the above interlocks 
indicate eitner a read or a 
write interlock. The next 5 
mask values indicate which 
of the control blocks are 
write interlocked. 



(Symbol (Data) 



Description 



DHDFBP 


A { 


DHDNBP 


N | 


DHDFDP 


N 1 


DHDPCO 


N | 


DHDCOP 


A | 


DHDISD j 


A | 


DHDCDP 


N | 


DHDNOP 


N j 


DHDMRL 


N | 


DHDNDH, 


W | 


DHDPDH 




DHDDUP 


A | 


DHDDXP 


A f 


DHDOXP 


A 1 



X , 0200 f SDST data set entry 
X'OaOO - RESTBL header 
X'0800 f Member descriptor in 

POD 
X'IGOO* POD 
X f 2000' External Page 

Entries 

The following H fields are 
used with VSAM organization: 

Buffer address 

Buffer size (pages) 

First data page checked out 
to this DCB 

Number of pages checked out 
to this DCB 

Overflow buffer 

VISAM directory location 

Current data page 

Current overflow page 

Maximum record length 

Forward and reverse DCB 
header pointers 

Address of duplex copy of 
the RESTBL 

Current External Page 
Address 

Overflow External Page 
Address 



H 



1 Seg 

Moxi 


ment 

Tium 




Control Entry and Hash Tabfe 
(CHASD5) 


Data Set and Member Entries 
(CHA5DE, CHASDM) 



Figure 19. Shared Data Set Table (SliST) 
Format 
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Table 31. Field Description of the SDST 
Header -- (CHASDS) 



Table 32. Field Description of a Member 
Entry — (CHASDM) 



| Symbol | Data | 

k .„ + „„ + . 

[5DSINTI L 

I 

I 
>DSLPN| N 



Description 



I f Symbol f Data j 



I 

ISDSSPTI N 



[SDSAVAj A 

I 

I 
jSDSDE | A 

i 
I SDSDME | A 

! I 
[SDSSDE| A 

I 

|SDSHAS| A 

I 

i 
I 

.SDSPLK| L 

I 

|SDSPSN| H 
_JL. 



ISUST interlock byte. If set, 
.access is not permitted 

Last page number assigned to 

(the SDST J • 

Last assigned Shared Page 
(Table (SPT) number 

|Next byte of available space 

| in the SDST 

| First deleted Data Set Entry 

| First deleted member entry 

| First Data Set Entry 

[First member entry for each 
j of the possible 64 hash 
[values of member names 

|VMA lock on SDS PSInJ 

j Public segment numoers 



— 4 y 



— — «+- 

SDMCHNI 


A 


- + 


SDMNURj 


N 




SDMSPT| 


N 




SDMNSP| 


N 




SDMFSPj 


N 




SDMJLSD| 


A 




SDMNAMj 


C 





Description 

Next memn^r entry in this 
hash alias chain 

Number- of users in this 
member 

Shared Page Table (SPT) 
number assigned to this 
member 

Number of shared pages 

Number of the first shared 
page 

Data Set Entry corresponding 
to this member 

Member name 



— X ^Jl_„_ __. 



I - . JL J. . _J 



ISA 



SDST 







(CHAISA) 








(CHASDS) 












IDATDT 
ISASDS 


(CHASDM) 














(CHASDE) 
f SDESPT, 
^ SDEFSP 














] 


r 




RESTBL 




DCB 










(CHARMS 




(CHADCB) 
DCBDEB 

DCBHD 


■DCBSP 
DCBSC 






1 


, TDT 


j 


. | 




___i*. 




(CHAEPE) 
















(CHAMHD) 














DHDLNK 

DHDRES 
DHDJFC 


DHDDCB 

(CHADHD) 

DHDPOD 




















































POD 
















(CHATDT) 


■* — ■ ' 














! 


1 — 


(CHAPOD) 


-* — ■ 




TDTDEB 


JFCB 1 

(TDTDDN) 








I 


(CHAPOE) 




j 




^ 


(CHAPOM) 2 
















JFCB 2 


(CHAPOM) 1 




















JFCB 

n 


(CHAPOM| n 





Figure 20. Linkage Relationships Among Control Blocks Used with VAM 
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Table 33. Field Description of a Data Set 
Entry -- (CHASDE) 



Symbol 
SDECHN 



T~" T 

Data 
A 



SDEINW 


L 


SDEINR 


L 


SDEJNN 


N 


SDEINI 


L 


SDEN11R 


N 


SDESPT 


N 


SDENSP 


N 


SDEFSP 


N 



SDENAM 



Description 

Next data set entry 

The next U bytes form a VAN 
interlock word which is 
updated by INTLK CCZCOH), and 
RJLINTLK CCZCOI) 

Write interlock 

Read interlock 

Count of read interlocks set 

Update interlock 
Number of users 

SPT number 

Number of shared pages 

Number of the first shared 
page entry 

Data S?t name 



Word 3 -- Address of 8-byte member name, 
zero if no member. 

Word ^4 -- Address of 1-byte type code: 

C - close 

O - open 

U - user count only 

todules Called : 

Interlock fCZCOHl) — Set write (W) inter- 
lock on a shared data set entry (SDSE) . 

Release Interlock CCZCOI1) — Release write 
(W) interlock on an SDSE. 

ABEND CCZACP) — - Abnormal termination of 
task. 

Normal - — For Open option: 
•00* Entry existed. 
•08 s New entry built, 
*10* Data set does not exist. 
For Close option: 
'00* Entry closed, users still exist. 



■04" Entry closed, no more users. 

•10* Data set do*-*s not exist. 

Error -~ ABEND i.; called when one ot the 
following conditions exist: 

• No po i n t e r tot he Pi ' B . 

• SDST or shared page table already 
locked by this task, 

• The data set is non-VAM. 

« Current pointer is higher than the 
"last page" pointer. 

• There is insufficient space for the 
member entry or data set entry. 

» An attempt is roade to close an unknown 
member or an unknown data set. 

• An attempt is made to access a non- 
shared data set by two different 
tasks. 

Operation : Overall operation of this 
module consisits of entry linkage, data set 
name search, member name search, analysis 
of user requirements, updating of data set 
entries and member entries, and either a 
normal return, an error return, or an 
ABEND. 

After completion of linkage and loading 
base registers from the parameter list, 
this module checks that the DCB code is 
present in the field DCBID. If unequal, 
ABEND is invoked. 

By use of test and set (TS) and time 
slice end (TSEND) , execution of this task 
will be delayed until the SDST interlock 
byte is found in the reset state. At that 
time, this task has exclusive control of 
the SDST, and a search through the chain of 
data set entries is made beginning with the 
SDSE specified in SDSDSE, by comparing the 
44 byte data set name in the JFCB with the 
data set name in each SDSE in the chain* 

If the end of the SDSE chain is reached 
before a matching data set name is found, 
or if no chain exists, an SDSE for that 
data set name does not exist — subsequent 
action depends on the option requested by 
the calling routine in the parameter list. 
When a matching name is found, this task 
will delay execution until the shared page 
table number (SDESPT) is not equal to 
X'FFFF* CSPT lock condition). If the lock 
condition is present, and this module was 
not called by ABEND for release of inter- 
locks, the portion of the SDSE search for 
the specified data set name which follows 
interlocking the SDST, will be repeated. 
Then if a member name was specified in the 
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list of input parameters , a search for that 
member name entry will be performed. 

The 8 byte member name is hashed to 6 
bits using the logical operation "exclusive 
or". That hash value is used to pick one 
of the 6*1 member entry chains,, and the 
selected chain is searched for the speci- 
fied member name. Each member name entry 
in the selected chain is compared against 
the member name specified in the parameter 
list. If equal , the data set name in the 
SDSE addressed by the member entry is com- 
pared. If both are equal, the proper memb- 
er entry has been found and will be pro- 
cessed by this routine. If no member entry 
chain exists or no matching member name is 
found or matching member names do not point 
back to the SDSE previously found, then no 
member entry exists. Continued processing 
depends on options specified in the para- 
meter list. 

The following describes processing fol- 
lowing data set and member name searches. 

If the SDSE was not present, and a memb- 
er name was specified, an error return is 
made. If a member name was not specified, 
and the option was CLOSE, an error return 
is made. Otherwise, a new SDSE is built, 
whether from the chain of deleted SDSEs or 
from available storage, and linked to the 
active SDSE chain with the user count set 
to one. Insufficient storage will cause 
ABEND. For VSAM or VISAM organization. 
Interlock (CZCOH1) is called to impose a 
write interlock on the SDSE if the OPEN 
option is non-Input. A return is then made 
to the user with a normal completion code 
and the address of the found SDSE in gener- 
al register 1. 

If the SDSE was present and a member 
name was not specified, the organization 
and operation will be checked prior to 
updating the SDSE. If this is not a VAM 
organization, ABEND occurs. If this is 
either a VSAM or VISAM data set (but not 
VPAM) to be opened, for OUTPUT, OUTIN, or 
UPDATE, the presence of an SDSE indicates 
that this data set has at least one user 
and is therefore not available to this 
task. If a VSAM or VISAM data set is to be 
opened for INPUT and a write interlock 
exists, the data set is not available. For 



either of thesf two cases, the interlock on 
the SDST will be released, and TSEND will 
be used to delay processing of this task 
until the other tasks have ceased to pro- 
cess that data set. Each time the task is 
reinitialized, the procedure to search for 
the SDSE will be started at the point 
(described above) where an interlock on the 
SDST is established by use of a TS. 



Where a VSAM or a VISAM data set is to 
be opened for input and a write interlock 
does not presently exist. Interlock is 
called to impose a write interlock on the 
SDSE if the open option is other than 
INPUT. It is not necessary to impose a 
read interlock, since the presence of an 
SDST entry without a write interlock 
implies a read interlock condition. The 
last operations to be performed are, to 
increment the user count in the SDSE* place 
the normal return code in register 15, the 
address of the SDSE in register 1 and 
return to the calling routine. This is 
done for VSAM or VISAM opened for input, 
and for any VPAM open. 

When the specified operation is CLOSE 
and no SDSE exists, the interlock on the 
SDST is released, and an error return is 
made to the calling program. 

When the specified operation is CLOSE 
and the SDSE was found and a member name 
was specified, the count of users will be 
reduced. If this count reached zero, the 
member entry will be deleted from the memb- 
er chain and its space appended to the 
deleted member chain. A return will be 
made to the user with a normal completion 
code. 

When the operation is CLOSE, the SDSE 
was found and no member name was specified; 
if the data set organization is VSAM or 
VISAM, Release Interlock is called to 
release the interlock that had been set on 
the data set-R read or write according to 
the OPEN option in the DCB. Following 
that, the user count in the SDSE is reduced 
by 1. If the count reaches zero, that SDSE 
is deleted from the chain of active SDSEs, 
and its space appended to the chain of 
deleted SDSE. A normal return is then made 
to the user. 
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SECTION 2; VAM VOLUME FC r tMAT AND DATA SET MAINTENANCE 



All direct access devices C2311 or 
2314) , on which VAM data sets reside, die 

initialized and maintained in a standard 
format. All space on these volumes, with 
the exception of cylinder 0, track ), and 
possibly cylinder 0, track l f is treated in 
units of 4096 bytes (one page) . Associated 
with each volume is a page assignment table 
(PAT) which contains entries for all of the 
pages on the volume. The length of the PAT 
depends on the type of device and currently 
occupies one page on the 2311 volume, and 
two pages on the 2 314 volume. This table 
is pointed to by a field in the volume 
label* 



Each entry in the PAT is 1 .byte long. 
If the first bit of the entry is zero, the 
page represented by the entry is either 
available for assignment to a data set or 
is already assigned* The remaining 7 bits 
provide a binary count of the number of 
data sets sharing the page. When this 
count is zero, the page is available for 
assignment. 

If the first bit of the entry is l f the 
page it represents is either a DSCB page or 
an error page. If the second bit of such 
an entry is 0, the entry represents a DSCB 
page, that is, the page contains data set 
control blocks (DSCBs} . Each DSCB page can 
contain up to 16 DSCBs and is, accordingly, 
divided into slots. When only 4 of these 
slots remain available on a page, one of 
two flag bits is set to one. This indi- 
cates that the page is only to be used for 
DSCBs which further describe data sets 
already included in that DSCB page. The 
second of these flags is set to 1 when all 
16 slots on the page are in use. The func- 
tion and format of the DSCBs will be dis- 
cussed further below* 

The third type of entry which can be 
found in the PAT is the error page entry. 
This entry represents a page which is 
unsuitable for use due to surface errors 
discovered by the RESTORE utility and is 
i r rii cated by a 1 in bits and 1* Follow- 
ing the page entries in the PAT, there are 
several unused bytes of space. The last 97 
words of this space are used for relocation 
entries. The last word in the table is a 
relocation control entry, which maintains a 
half-word count of the number of relocation 
entries which precede it, and a half word 
CX'FFFF') if there are any entries. The 
other 96 words may be occupied by reloca- 
tion entries. These entries contain the 
relative page number of the error page, and 



the relative page number of the n location 

page. 

THE DATA SET CON TROL BLO CK (DS CB) 

Associated with each data set is one or 
more DSCBs. The first of these control 
blocks is called a forma t-E DSCB; if addi- 
tional space is required to describe the 
data set, forma t-F DSCBs are built and 
chained to the format~-E DSCB. A data set 
and the DSCBs which describe it may be on 
more than one volume. Because of this, the 
chaining procedure used qives the relative 
volume number and the relative page number 
on that volume where the next DSCB is 
located. Also, sinc^ each DSCB page con- 
tains up to 16 DSCBs, the slot number of 
the DSCB is included. Each forma t-E DSCB 
contains the data set name and properties 
and possibly the external page entries 
which give the location of the data set 
pages on external storage. Thesr- entries 
contain the relative volume and relative 
page number on the volume where the data 
set. page is located. 

The concept of relative volume numbers, 
introduced above, arises from the possibi- 
lity of a data set occupying more than one 
volume. For public data sets, this rela- 
tive volume number provides an indexing 
factor into the public volume table. This 
table consists of a 16 byte header, which 
contains a count of the maximum number of 
public volumes allowed, and the count of 
public volumes actually in use. Following 
the header is a series of 16 byte entries 
representing each volume assigned to public 
storage. The entry contains the volume ID, 
the device code, and the symbolic device 
address of the volume. This information, 
in conjunction with the pathfinding tables 
and the pathfinding routine of the resident 
supervisor, make it possible to locate all 
volumes which contain a given data set* 

The public volume table is a separately 
assembled CSECT which is a part of initial 
virtual storage and is initialized by Star- 
tup. In order to maintain similarity in 
the processing of public and private data 
sets, a table, called the private volume 
table, is built for private volumes* The 
address of the volume table is placed in 
the RESTBL header by OPENVAM. 

The content of the DSCBs for a data set 
also vary according to whether the data set 
is public or private. Within the field of 
data set properties is a count of the numb- 
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er of volumes which the data set occupies. 
For public data sets this count is zero 
since the list of volumes is contained in 
the public volume table. In this case, the 
data set name and properties field is fol- 
lowed immediately by a list of external 
page entries. Lach of these entries con- 
sists of a relative volume number which 
provides an index into the public volume 
table and a relative external page number, 
which provides an index into the page assi- 
gnment table on that volume. For private 
data sets residing on one volume, this 
field is also zero since the volume ID is 
contained in the data set descriptor. For 
multivolume private data sets, the data set 
name and properties field is followed by a 
list of the volume IDs on which the data 
set resides. This list is used by MOUNTVOL 
when it builds the private volume table. 
The format-E DSCB may contain up to 25 
volume IDs each 6 bytes long. Following 
the list of volume IDs, is the list of 
external page entries which are the same as 
for public data sets. 



or deleted completely. When this occurs, 
the affected pages must be added to or 
deleted from the data set and the task's 
RESTBL. For this purpose, six service rou- 
tines are provided with the virtual access 
irethod: 

Insert/Delete Page (CZCOD) — Effects the 
addition or deletion of pages in a data 
set and performs error checks to deter- 
mine the validity of the operation. 

Insert (CZCOF) -- Adds external page 

entries representing the new pages to 

the task's RLSTBL. 

Request Page CCZCOE) — Provides Insert 

with a list of available pages for ins- 
ertion into the RESTBL, It also marks 
the pages in use and unavailable for 
assignment. 

Expand RESTBL (CZCQI) — Increases the size 
of the RESTBL for nonshared data sets 
when the addition of new page entries 
causes an overflow condition. 



BUILDING AND MAINTAINING A DATA SET 

When a user is building or updating a 
data set, he conceives of it as being a 
group of contiguous pages of records. 
Actually, because of the virtual storage 
concept, the pages of any data set may be 
physically located in several external 
areas known as extents. In order to allow 
the user to continue to think of the data 
set in terms of contiguous pages, it is 
necessary to construct a relative page/ 
external page correspondence table 
(RESTBL) . This table is built by OPENVAM 
when a data set is first opened for use. 
The RESTBL consists of a header which con- 
tains information such as the number of 
pages available for assignment to the task, 
the number of pages currently in use by the 
task, and the relative location of the 
first unused page which can be assigned to 
the task. The balance of the RESTBL con- 
sists of a series of external page entries 
which are identical in format to the 
external page entries in the DSCB described 
above. This parallel construction of 
external page entries enables the system to 
assign and delete pages in a data set, and 
to update the availability of the pages on 
the volume, without the use of conversion 
routines. 

The external pages assigned to a task 
are also placed in the user's external page 
table or shared page table so that a 
reference to a virtual storage address is 
translated to the correct main storage 
address during execution. 

During execution, a data set may be 
dynamically increased or diminished in size 



Reclaim CCZCOG) — Deletes page entries 
from a task's RESTBL and adds them to 
the available list for future assignment 
or release at the time the data set is 
closed. 

DELVAM CCZCFT) — Deletes a virtual organi- 
zation data set by deleting its catalog 
entry and freeing the external pages and 
DSCB slots which it occupies. 



Insert/Delete Page Routine (CZCQD) 

The Insert/Delete Page routine is called 
by FLUSHBUF (CZCOV) , GETPAGE CCZCPI) , and 
Add Directory Entry (CZCPL) to check and 
perform insertion or deletion of pages 
within *a data set. The validity of the 
request is checked, based on the specific 
request and on parameters in the DCB and 
RESTBL. (See Chart KA.) 



Entry Points : 

CZC0D1 -- Insert pages, entered via type-1 
or type- 2 linkage. 

CZC0D2 -- Delete pages, entered via type-1 
or type-2 linkage. 

Input ; Register 1 contains the address of 
the DCB. Two fields which must be set in 
the DCB are: 

DCBN — - Page number, relative to the data 
set or member, at which the operation is 
to take place. 

DCBM -- Number of pages to oe inserted or 
deleted. 
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Modules Called : 

Insert (CZCOF1) -- Insert additional pages 
at a specified position within a data 
set and move all other active pages 

upward. 

Reclaim CCZCOG1) -- Delete specified pages. 

Interlock (CZCOB1) -- Set a write interlock 
in the RESTBL external page entry. 



Release Interlock CCZCOI1) — 
information on RESTBL. 



Release write 



GETNUMBR CCZCOOl) — Validate and perform 

insertion or deletion on a partitioned 
data set. 

TSEND CCEAH19) — Force end of time slice 
for this task, to wait for interlocks in 
shared pages to be released by the task 
that had set them. 

VDMEP (CZCQK1) — Output a diagnostic mes- 
sage and terminate the function (but not 

the task) . 



Exits: 



Normal — Return to the calling routine 
with one of the following return codes: 



'00' 



Normal. 



•04* No storage space available. 

•08* Storage ration exceeded- 

f 0C f No secondary storage allocation 
specified, 

s 10 f Shared data set RESTBL cannot be 
expanded, 

•iu f Maximum data set/or member size 
exceeded, 

*18 s Insertion beyond end of data set, 

f lC s Deletion beyond end of data set. 

Error — VDMEP is called and the function 
(not the task) terminated if an invalid 
return code is received from Reclaim, 
Insert, or GETNUMBR. 

Operation ; Calls to CZCOD are for the log- 
ical insertion or deletion of data pages 
within a data set. If the routine is 
entered at the primary entry point 
(CZCOD1), the Insert flag in the DCB opera- 
tion field CDCBOP) is set to insert 
CDCBOP4) . If entry is made at the secon- 
dary entry point CCZCOD2) in the case of a 
deletion, no indication is set at this 
time. The code from these two types of 
entries converges to perform module 
initialization. 



Initialization and general register 
storage is executed in conformance with 
linkage conventions. Base registers are 
declared for the calling program's save 

area. CZCOD CSECT and PSECT, DCB, DCB 
header and RESTBL. 

Insertions or deletions may not bo done 
on data sets which are opened ior input 
only. If the DCB open option indicates 
input, ABEND is called immediately. The 
RESTBL is interlocked for shared data sets. 

If the data set is partitioned, GETNUMB- 
ER CCZCOO) must be called. The requested 
operation is tested. If the Insert flag is 
not set as descrbied in the entry proce- 
dure, the Delete flag (DCBOP5) is set and 
GETNUMBR called. Upon a successful return 
from GETNUMBR, control is returned to the 
user by the RETURN macro, since GETNUMBR 
has already accomplished the desired inser- 
tion or deletion. 

For nonpartitioned data sets, CZCOD per- 
forms a great deal of the consistency and 
validity check required for the insertion 
or deletion. 

The extent of a deletion, that is, the 
first page plus the number of pages being 
deleted, must be contained within the data 
set. If any of the pages to be deleted 
falls outside of the range of the data set, 
ABEND is called. 

Reclaim CCZCOG) is called to accomplish 
the deletion. The return code from Reclaim 
is tested for errors. If general errors 
exist or the deletion was requested on 
pages of a shared data set that were inter- 
locked, an appropriate return code is set 
and control returned to the caller. Upon 
successful deletion, control is returned to 
the caller by the RETURN macro. If the 
data set is shared, the RESTBL interlock is 
released before returning. 

An insertion must be made within the 
range of the data set or contiguous to the 

last page. If the insertion is requested 

outside or not adjacent to the data set, an 

appropriate return code is set and control 
returned to the caller. The actual inser- 
tion of the data page is performed by 
Insert CCZCOF) . The return code from 
Insert is tested for errors. If they 
exist, VDMEP is called. Control is 
returned to the caller by the RETURN macro. 
For shared data sets the RESTBL interlock 
is released before returning. 



Insert Routine CCZCOF) 

Insert is called by Insert Page CCZCOD) , 
Extend POD CCZCOM) , and GETNUMBR CCZCOO) to 
insert additional *in use® pages in the 
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RESTBL of the data set involved in the 
request. (See Chart KB.) 



Attribute ^;: 
privileged. 

Entry Point : 
linkage. 



Redd-only, reentrant, 



CZCOF1 -- Entered via type-1 



Input : Register 1 contains the address of 
the DCB. Fields used in the DCB are: 

DCBN -- First page of data set involved in 
request C nonpartit ioned) . 

DCBNI — First page of data set involved in 

request (partitioned) . 

DCBM -- Number of pages involved in 

request. 



DCBOP 



Type of operation requested. 



Modules Called ; 

Request Page (C2COE1) — Flags additional 
external page entries "in use* in the 
available page chain in the RESTBL* 
Request Page will also atteir.pt to 
increase the number of pages available 
to the task, by calling FINDEXPG, when a 
sufficient number of pages is not avail- 
able to fill the request. 

VDMEP (CZCQK1) — Output a diagnostic mes- 
sage and terminate the function (but not 
the task) . 

Exits ; 

Normal — Return to the calling routine. 

Error — - A valid error code returned from 
REQPAGE is passed back to the calling 
routine in register 15, An invalid 
error code returned from REQPAGE results 
in VDMEP being called. 

Operation : When Insert is first entered, 
registers are saved and base registers 
established for the CSECT f PSECT, DCB, DCB 
header , and RESTBL header. Insert then 
retrieves the number of the first page to 
be inserted and the total number of pages 
to be inserted from the DCB. Next, the 
virtual storage addresses of the next 
available P 3 ^ and of tne location of the 
insertion are computed, and a call is made 
to Request Page (CZCOE) . Request Page will 
flag the requested number of pages "in use" 
by setting the flag in the external page 
entries in the RESTBL. If a sufficient 
number of pages are not available to fill 
the request, an attempt is made to add 
pages to the available list from external 
storage. If Request Page is unable to fill 
the request, an error return is made to the 
calling routine by the RETURN macro 
instruction. 



Insert may be called to insert pages 
between existing pages of the data set or 
to simply add pages to the end of the data 
set. In the latter case, Request Page will 
have added the new pages at the end of the 
list of "in use" pages and no additional 
work is required of Insert. If pages are 
being added between existing pages, it is 
necessary to create a gap in the list of 
"in use" pages in the RESTBL. For this 
purpose, a 64-word work area is provided in 
the PSECT. This area will hold 32 shared 
or 64 nonshared external page entries. The 
new entries are moved into this work area 
starting from the beginning of the avail- 
able list. All current "in use" entries 
following the point of insertion are moved 
back in the RESTBL an equal number of words 
to create a gap. The new page entries are 
then moved from the work area to the gap 
thus created. This procedure is repeated 
until all new entries have been inserted. 

In the case of duplexed data sets, this 
process is repeated for the secondary copy, 
after which the DSCB integrity bit is set 
and a normal return is made to the calling 
routine . The setting of the integrity bit 
will cause CLOSEVAM to call Write DSCB to 
update DSCBs on the volumes. In this mann- 
er, pages dynamically added to the data set 
are made unavailable for future allocation. 

Note that this routine does not inter- 
lock the RESTBL for shared data sets. This 
is so because Insert assumes that the cal- 
ling routine had done so before calling it. 
Also, Request Page is responsible for 
updating the counts of external pages in 
use, available pages, and the relative 
location of the first available page. 

Expand RESTBL Routine (CZCQI) 

Expand Relative External Storage Corres- 
pondence Table is called by OPENVAM 
(CZCOA) , MOVEPAGE (CZCOC) , Request Page 

(CZCOE), and Find (CZCOJ) to increase the 
size of the RESTBL by one page. The addi- 
tional space appears between the external 
page entry words, and the DCB and member 
header control blocks. Note that a RESTBL 
which resides in shared virtual storage 
cannot be expanded. (See Chart KC.) 



Attributes s Read-only, reenterable, 
privileged. 



Entry Point : CZCQI1 — Via type-1 linkage. 

Input : Register 1 contains the address of 
the RESTBL to be expanded. 

Modules Called : VMA (CZCG4) — To increase 
the size of a specified virtual storage 

area . 
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Normal -- Execution of the calling program 
is resumed by use of RETURN. No special 
return code is given. 

Error --- None. 

Operation: Initialization and general 
register storage is executed in confonrance 
with linkage convention- Base registers 
are declared for the CSECT and PSECT, a 
save area, RE5TBL # DCB header and JFCB. 

Expand RESTBL calls Expand (CZCGU) by 

the CALL macro to expand the virtual 
storage of the RESTBL by 1 page. After the 
expansion, the RESTBL pointers, are opiated 
in the JFCB if the RESTBL was relocated in 
the expansion. RESTBL pointers CVM 
addresses) within the DCB and member head- 
ers are updated if the RESTBL has been 
relocated. 

The DCB and member headers are moved on 
to the new page up to the top header; this 
creates space between the external page 
entries and headers, for the insertion of 
new information- The relative pointers 
within the headers, and the DCB and member 
headers are updated by 4096 to reflect 
their new position. 

When the new virtual memory space has 
been obtained , and all pointers and 
addresses which need to be adjusted have 
been updated. Expand RESTBL returns to the 
calling module by the RETURN macro. 

Note that a RESTBL which resides in 
shared virtual storage cannot be expanded. 

Requ est Page Routine CCZCQE) 

Request External Pages is called by 
Insert CCZCOD) and OPENVAM CCZCOA) for the 

purpose of assigning available external 
pages to a data set- If sufficient pages 
are not available to fill the request, an 
attempt is made to increase the size of the 
aata set by calling FINDEXPG CCZCEL) . The 
newly assigned pages are added to the 
task f s RESTBL or, in the case of a shared 
data set, to the shared RESTBL* If this 
addition results in an overflow of the 
RESTBL, it is expanded to accommodate the 
extra pages in the case of nonshared data 
sets. Since a shared RESTBL cannot be 
expanded, this condition results in a call 
to" VDMEP CCZCQK1). (See Chart KD.) 

Attributes : Read-only, reentrant, 
privileged. 

Entry Point : CZCOE1 — Entered via type-1 
linkage. 

Input ; Register 1 contains the address of 
the DCB. Fields used in the DCB are: 



DCBM -~ Number of paqes requested. 

DCBN -- Relative number of the first page 
affected. 

Modules Called : 

Expand RESTBL (CZCQI1) — Increases the 

size of the RISTBI, for a nonshared data 

set when the inclusion of the newly 
assigned pages causes overflow of the 

current RESTBL. 

FINDEXPG CCZCEL1) ~ Assigns additional 
external pages to the task from the 
storage allocated to the task. 

VDMEP (CZCQK1) — Output a diagnostic mes- 
sage and terminate the function (but not 
the task) . 

Exit s: 

Normal -- RETURN to the calling routine if 
successful or if the request is for zero 
pages with one of the following return 
codes in register 15: 



-00 1 



Normal. 



•04* No external storage available. 

•08' Storage ration exceeded. 

S 0C* No secondary storage allocation. 

•10' Shared data set RESTBL cannot be 
expanded. 

Error -- VDMEP is called if an invalid 
return code is received from FINDEXPG 
CCZCEL1) . 



Operation : Initia 
register storage i 
nance with standar 
base registers are 
CSECT, PS^CT, DCB, 
RESTBL. The numbe 
the request (DCBM) 
request is for no 
made to the user* 



lization and general 
s performed in confor- 
d linkage conventions and 
established for the 

DCB header, and the 
r of pages involved in 
is checked and, if the 

pages, a normal return is 



The function of Request Page is to 
assign external pages to a task's data set 
from external storage which has been pre- 
viously allocated. These pages may be 
assigned from either the primary or the 
secondary allocation if it ie be assigned 
from either the primary or the secondary 
alocation if it exists. Additionally, the 
page entries in the RESTBL are flagged "in 
use* and any pages which have been assigned 
are added to the RESTBL, 

These operations differ in two ways for 
shared or nonshared data sets. In the case 
of shared data sets, two words of RESTBL 

space are required for each page entry? the 

additional word is occupied by the page 
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interlock required for shared data sets. 
The other difference is that the RESTBL 
cannot be expanded for shared data sets. 



Following 
the data set 
is shared. 

noted differ 
same; the ex 
in the folio 
the RESTBL i 
if sufficien 
If they are, 
in the RESTB 
the count of 
the location 
(RHDNAP) are 
is made to d 
data set and 
still be pro 
REQUEST PAGE 
test for "no 
repeats the 
not duplexed 
oeen process 
the caller. 



the initialization process, 

is examined to determine if it 
With the exception of the above 
ences, the processing is the 
ception.> will also be mentioned 
winq description. In each case 
s tested (RHDNEP) to determine 
t pages are already assigned. 

the pages are flagged "in use" 
L external page entries, and 
available pages (RHDNEP) and 
of the next available page 
updated in the kESTBL. A test 
et ermine if this is a duplexed 

if the secondary RESTBL must 
cessed. If both are true, 
loops back to the point of the 
pages requested" , above, and 
procedure. If the data set is 

or if the secondary copy bas- 
ed, a normal return is made to 



If Request Page finds that there are not 
sufficient pages assigned, it attempts to 
assign sufficient pages from the secondary 
space allocation (the usgz may have 
requested up to 256 pages) . If no such 
allocation was made, a call is made to 
ABEND. If such allocation was made, the 
RESTBL is examined to see if there is 
enough available space in the RESTBL to 
hold the new external page entries. This 
space exists in the RESTBL between the 
existing entries and the headers which are 
at the end of the RESTBL. If the RESTBL 
does not contain enough space and the data 
set is shared, a return is made to the 
caller with an error return code. If the 
data set is not shared, a call is made to 
the Expand RESTBL routine to provide the 
space required. Following this call or if 
the RESTBL contained sufficient free space, 
a call is made to Find External Page 
CCZCEL) . Find External Page will return 
the addresses of 256 pages to be assigned, 
or the remainder of the secondary alloca- 
tion if it is less than 256 pages* If the 
data set is not shared, this list is moved 
directly to the RESTBL following the last 
previous entry. If the data set is shared, 
the entries are moved, one by one, from the 
return area to the RESTBL, and each entry 
is preceded by a full word of zeros which 
serves as the interlock word for the page. 
For both types of data set a switch is set 
to indicate that the DSCB should be 
updated, and the number of available pages 
is updated in the RESTBL (RHDNEP) . Request 
Page then returns to check if enough pages 
have been assigned- This procedure is 
repeated until enough pages are made avail- 
able to the task or until the secondary 



space allocation is depleted. In the latt- 
er case a call is made to ABEND. 

When the request for pages is satisfied, 
each page entry is flagged " in use w and the 
next available page location (RHDNAP) is 
adjusted. Finally, the checks for duplexed 
data set end secondary RESTBL update art- 
repeated. If a secondary RESTBL must be 
processed, control is returned to the point 
of check for no pages? otherwise, a return 
is made to the caller with a normal return 
code. 

Reclaim Routine (CZCQG) 

Reclaim is called by Delete Page 
(CZCOD), GETNUMBR CCZCOO), and Stow (CZCOK) 

to deleft e external page entries from the 
"m use" list in the RESTBL and place them 
in the available list. This has the effect 
of removing the pages from the data set, 
but the pages remain allocated to the task 
and may be reassigned at some future time. 
(See Chart KE. ) 

Attributes : Read-only, public, privileged. 

Entry Point : CZCOG1 -- Entered via type-1 
linkage. 

Input : Register 1 contains the address of 
the DCB. Fields used in the DCB are: 

DCBNI -- First page to be deleted Cpar- 
tioned data set ) . 

DCBN — First page to be deleted Cnonparti- 
tioned data set) . 

DCBM -- Number of pages to be deleted. 

Module Calle d: ABEND (CZACP1) — Abnormal 

task termination. 

Exits : ' 

Normal ™ Return to the calling routine. 

Error -- A return code of *04' is set in 
register 15 if the request is to delete 
shared pages which are interlocked. 
ABEND is called if the data set organi- 
zation is VPAM. 

Operation : The operation of Reclaim is 
essentially the same for shared and non- 
shared data sets. In the case of duplexed 
data sets, the process is repeated for the 
secondary RESTBL in order to maintain sym- 
metry between the copies. 

The function of Reclaim is to mark the 
deleted pages not in use and to add them to 
the available list in the RESTBL. This is 
accomplished by setting the proper flags in 
the external page entries in the RESTBL, 
and by moving the external pages entries 
from the chain of w in use" entries to the 
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v.Yien Reclaim is entered, registers are 
saved in conformance with linkage conven- 
tions and base registers are established 
for the CSECT, PSECT, DCB # DCS header, and 
the RESTBL header. The number of pages to 
be deleted is checked and # if zero, control 
13 returned to the user. If there are 
pages to be deleted, the address of the 
first external page entry to be deleted is 
computed, together with the amount and 
address of unused space in the RESTBL. 

At this point , the processing for shared 
arid nonshared data sets diverges. The dis~ 
tinction arises from the difference in the 
size of the external page entries (8 bytes 
uC.s: shared, k bytes for nonshared). The 
processing is logically identical for both 
and the following description applies to 
'oozh m 

The amount of available space in the 
RESTBL is compared to the amount of space 
required to hold the deleted entries. If 
the space is large enough , the deleted 
entries are moved from the "in use" chain 
to thrit area, the entries are flagged as 
not in use, and the entries following the 
gap left by the deletion are moved up to 
close the gap. 

If the amount of available space is not 
large enough, a 64-word work area in the 
PSECT is used for intermediate storage of 
the entries. Up to 32 shared or 64 non- 
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shared entries are moved from the "in use" 
chain to the work area, and are flagged 
not in use. The qap left by this dele- 
tion is closed and the deleted entries 
are added to the end of trie chain of 
available entries. This process is re- 
peated until all deletion entries have 
been processed. 

Following the movement and flagging of 
entries, the data set is checked to see if 
it is duplexed and if the secondary RESTBL 
remains to be processed. If both condi- 
tions are met, the entire process is 
repeated for the secondary RESTBL. When 
all entries for ail copies of the data set 
have been handled, the DSCB integrity bit 
(REDFLG) in the RESTBL header is set, to 
cause the updating of the DSCBs on the 
volume or volumes, and control is returned 
to the caller. 



DELVAM Routine (CZCFT) 



^igure 21. Deleting Pages from the "In 

Use" List in RESTBL 



Delete a VAM Data Set is called by Erase 
CCZAEJ) , ADDCAT (CZCFA) , and Recreate Pub- 
lic Storage (CZAXX) to delete a VAM data 
set by deleting its catalog entry and mark- 
ing all its DSCB and data page entries 
"available" in the page assignment table, 
If the data set is private, the volume or 
volumes on which it resides are demounted. 
Optionally , the associated JFCB may be de- 
leted. (See Chart KF.) 

Attributes : Read-only, public, privileged. 

Entry Points : 

CZCFTT^^^^Main entry, entered via type-1 
linkage. 

CZCFT2 -- For generation data groups only, 
entered via type-1 linkage. 

In put : On entry, register 1 contains a 
pointer to a three-word parameter list: 

Word 1-— If entered at CZCFT1 , a pointer 

to a 35-character (without userid) data 
set name. If entered at CZCFT2, a 
pointer to a 44~character (includes 
userid) data set name. 

Word 2 ■ — A pointer to the JFCB to be 
deleted if that option is chosen. 

Word 3 ~ A pointer to the JFCB deletion 

indicator. This indicator is a one byte 
flag which is set to X'OO' if no dele- 
tion is to be done or to X'80' if the 
JFCB is to be deleted. 

Modules Called : 

FINDDS (CZAEC1 or CZAEC2) -- Locates or 
creates a JFCB for the data set when a 
pointer to one is not provided by the 
calling routine. 
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JUOCFQN CCZCFL2) -- Get T-block to see if 
BULK I/O pending. 

SETXP CCEAH7) — Prepares the external page 
table to allow a virtual storage page to 
be read in. 

Search SDST (CZCQE1) -- Provides a count of 
users currently sharing the data set. 

RELEXPG CCZCEN1) — Called to release all 
data pages and DSCB slots used by the 
data set and allocates them for future 
assignment on the volume. 

DEIjCAT CCZCFD1) -- Deletes the catalog en- 
try for the data set. 

FREEMA1N (CZCHA3) — Frees the space occu- 
pied by the private volume table. 

RELEASE (C2AFJ3 or CZAFJ6) — Release the 

JFCB when that option has been 
specified. 



READWRIT CCZCEM) 



Read in DSCB page. 



DSCBREC (CZCEF1) ~- Attempt recovery on a 

read DSCB error. 

WTL (CZABQ1) — Send message to operator 

and record it in the system log. 



Exits ; 

Normal — Return to the calling routine 
with one of the following codes in 

register 15: 

s 00 f Data set deleted. 

s 04 s Deletion not made due to open 
DCBs. 

•08* No deletion due to active 
sharer. 

'0C* No parameter list passed or FQN 
not indicated by Word 1. 

•10* Shared data set not owned, not 
unlimited access. 

•14 • DSORG not VAM, 

'1C Delete option specified, with 
JFCB pointer . 

Error -- Before continuing, a message is 
written to the system operator and sys- 
tem log via WTL under any of the follow- 
ing conditions; 

• When a good return code is not 
received from RELEXPG. 

* When an attempt to recover a DSCB with 
a bad checksum is unsuccessful. 



• When end-of~DSCBs occurs before end- 
of -volume fields. 

Operatio n: Gn main or secondary entry, 
DELVAM saves input registers and estab- 
lishes base registers tor the CSECT and 
PSECT in conformance with linkage conven- 
tions. The secondary entry, at CZCFT2, 
allows a generation data group flag to be 
turned on, and then joins the main logic. 
The input parameter list is now checked for 
the presence of fully qualified name. If 
none is present, an error return is made to 
the calling routine. If the FQN is pre- 
sent, a test is made for the presence of a 
JFCB address. If no such address is given, 
a call is made to FINDDS, to find a JFCB or 
to create one. For a generation of a 
generation data group data set, FINDDS is 
called at a secondary entry point, CZAEC2, 
using the user id specified in the input 
parameter list. Otherwise, FINDDS is 
called at CZAEC1 and task common will be 
referenced for the userid. Once the JFCB 
has been located or created, tests are made 
to determine if only one DCB is open and if 
the data set is VAM organization. If eith- 
er test fails an error return is made to 
the calling routine. 

If DELVAM was called by LOGOFF, ABEND, 
or Close, a call to LOCFQN is made to check 
for Bulk I/O pending. If it is pending, 
normal return is immediately made to the 

caller. 

Next the data set must be tested for 
sharing. This is determined by a call to 
Search SDST. If the data set is sharei, 
only one user may be currently accessing 

the data set and the user deleting the data 

set must be either the owner or a sharer 
with unlimited access. If either of tiese 
conditions is not met, an error return is 
made to the caller. 

Once this testing is complete or if tne 
data set is not shared, DELVAM checks :o 
see if a RESTBL exists. If one does ecist, 
the data set is still open and it must be 
closed, calling Release at CZAFT6. Once 
the DCB is closed or if it was closed '"O 
begin with, a test is made to see if there 
is a DSCB. If none exists, there are no 
pages in the data set and processing wi.ll 
continue with the JFCB release described 
below. 



Data Set Page Release 
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DSCB is then read in turn. For private 
volumes there may be several volumes in the 
volUiYie list. These entries are skipped 
over until the external page entries are 
lound. These e>cternai page entries are 
then moved to a parameter list area in pre- 
paration for a call to RELEXPG- WhC'n the 
parameter list is full or when all external 
;/cuje entries have been moved to the list, 
^ZLEXFvi is called to perform the re]. ease. 
\he pages are marked available for assign- 
ment, in the page assignment table. This 
procedure is repeated until ail external 
'j;a s r e£ have been released. If, in the pro- 
cess of releasing pages f an entire DSCB 
page is cleared of DSCBs, the DSCB page is 
also added to the parameter list and it is 
•released. Any errors encountered in 
KELEXPG result in messages to the system 
operator and log* 



JFCB Release: Following the release of 
wet atrial pages, the pointer to the dummy 
REJTBL is cleared- Then f or if the data 
set had no pages , the JFCB deletion indica- 
tor is tested. If no deletion is 



requested* processing continues with Cata- 
log Deletion below. The JFCB is released 
by calling Release. An error return from 
that routine results in messages to the 
system operator and log. 



Catalog Deletion : If the catalog entry is 
to be deleted, a call is made to DELCAT to 
perforin the deletion* If an error return 
is received from DELCAT f the operator is 
notified and it is recorded on the system 
log via WTL. The catalog entry will not be 
deleted if the data set had no external 
pages, if DELVAM was entered by the Recre- 
ate Public Storage routine, or if the data 
set is OSERCAT or SYSCAT. Following the 
deletion of the entry or if no deletion is 
performed, the exit procedure is entered. 
This process involves testing to see if the 
data set is public or private. For private 
data sets, a call is made to FREEMAIN to 
release the virtual storage occupied by the 
private volume table. DELVAM then returns 
to the calling routine by means of the 
RETURN macro instruction. 
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A read interlock prevents a user from 
writing to a data set, data set member, or 
data set page. A read interlock is never 
actually placed on a data set. The inter- 
lock is implied by the presence of an entry 
for the data set in the shared data set 
table* When a user attempts to open a data 
set, the shared data set table is searched. 
If there is an entry in the table for the 
data set, the write interlock is tested. 
If that interlock is set, no other task may 
access the data set. If the write inter- 
lock is not set, a read interlock is 
assumed and a second task may open the data 
set for any operation which would impose a 
read interlock. Several users may there- 
fore have simultaneous read access to a 
data set but if only one user has write 
access to it, no other user's task is 
allowed any access. Read interlocks are 
set on pages of a shared indexed sequential 
data set. This interlock prevents other 
users from writing to the interlocked page 
but permits them to read from it. 

A write interlock prevents read or write 
access to shared data by any user other 
than the one who caused the interlock to be 
set. Only one write interlock can be set 
on a given data set at a time and once set, 
it precludes the setting of read interlocks 
on the data set. Additionally, if a read 
interlock is in effect on a unit of data, a 
write interlock cannot be set. 

Interlocks are maintained in various 
tables depending on the data set organiza- 
tion. Regardless of the table which con- 
tains the interlock it is maintained in a 
four byte field called the interlock word. 
This field is aligned on a word boundary 
and has this format: 

fw I R TnT* I 

L JL X JL—J 

W - write interlock 
R - Read interlock 



N - Number of interlocks currently set 

1 - Interlock for changing bytes R and N 

A virtual partitioned data set is inter- 
locked at the me moor level. The interlock 
word for each member of a partitioned data 
set is contained i n the member header in 
the RESTBL (CHAiMHD) . The interlock is set 
according no the organization of the member 
and the option specified in the OPEN macro 
instruction. The interlock is set when the 
FIND macro instruction is issued, and 
released when the- STOW macro instruction is 
issued or when the data set is closed. 
Table 3 4 lists the open options, and the 
type of interlock which is set for each. 
Shared access for members depends on the 
organization of th«~- member as discussed 
below. 

Virtual sequential data sets are inter- 
locked at the data set level. The inter- 
lock word for these data sets is located in 
the data set entry of the shared data set 
table CCHASDE). The type of interlock 
imposed depends on the option specified in 
the OPEN macro instruction. Table 35 lists 
these options and the applicable interlock. 
The data set is interlocked when it is 
opened and the interlock is released when 
the data set is closed. Since several 
users may have simultaneous read access to 
a data set, a count is maintained of the 
number of users currently accessing the 
data set. As each user opens the data set, 
the count of users is incremented. As each 
user issues the CLOSE macro instruction, 
the count is decremented and only when it 
reaches zero is write access permitted. 

A virtual indexed sequential data set or 
member is interlocked at the page level as 
well as at the data set level. That is to 
say, while one user is reading from one 
page of a data set, other users are 
restricted in their access to that page, 
but may access other pages in the data s€ j t 
assuming that the type of access attempted 
does not violate the data set or member 
level interlock. The paqe level interlock 
words for virtual index sequential data 
sets are contained in the external page 
entries CCHAEPE) in the RESTBL. One word 
of interlocks exists for each page of the 
data set and the locks are set and reset by 
the Movepage routine CCZCOC). Table 36 
lists the effects of various open options 
on page level interlocks. 

A page level read interlock is placed on 
a page when a GET or type-KY READ macro 



Section 3: Data Set Sharing 127 



Table 34. Effect: of OPEN Option on Member 

Interlocks in Member Header 
r __. . _ T ___„„. __ — . _. — 1 

jOPEN Optionf Interlock ^P^ *Set by FIND) | 
H „„„„„ + „.„_„-„„ . _„ H 

| INPUT IREAD | 

i.„„ — _„.4_„— „„„__„ — . „. H 

i OUTPUT | WRITE \ 

iIN^-;;-T (WRITE CVSAM member) | 

jGUTIN {READ CVISAM member) ( 

! UPDATE I | 

L_„ „. ._A_ ___. . __. . ._ .—.-J 



references a page other than the one in 
which the write interlock is set. 



CONTROL TABLE INTERLOCKS 

VAM has two control tables which reside 
in shared virtual storage - the RESTBL and 
the SDST. Routines which manipulate these 
tables must interlock them to prevent them 
from being changed while in use. These 
interlocks do not have the conventional VAM 
interlock word format. 



Table 35. Effect of OPEN Options on Data 

Set Interlocks in SDST 
r „ ___ _ T . — „___ T _ — . . 1 

(OPEN Option |VSAM ( VIS AM | 

l.__„„_„„a„„„„„„ + „„„„. -f 

i INPUT 1 implied READ [Implied READ) 

H „„„„„_ + _„_„ „ + „ „. ._< 

jOJTPUT (WRITE (WRITE | 

l_„„„„„„ + „„„_+- _-„_4 

I INOUT | | | 

; OUT IN J WRITE (Implied READ) 
j UPDATE | | I 

; Mote : No interlocks are set on VTAM j 

"data sets at OPEN time. | 



Table 36. Effect of OPEN Option of VISAM 
Page Level Interlock 



I j Interlock) 

IOPEN Optionj Type | 



When Set 



, INPUT 



j UPDATE 

t 
t 

; INOUT 

1 

|OUTIN 

I 

i 

i 



j OUTPUT 

L — 



IREAD 
. + _ .. 

I WRITE 



fREAD 



-+ 

(None 

-A 



i When page is read 



| READ Exclusive, 
(Write by new key, 
| WRITE replace by 
(key, DELRAC 
fREAD by key and 
| all other opera- 
tions causing a 
(page to be read 



instruction is issued. A page level wirte 
interlock is set by the type-KX READ macro 
instruction which also releases a page 
level read interlock set by that task. 
Other macro instructions which release a 
page level read interlock when issued by 
the task which set it are WRITE, ESETL, 
DELREC, RELEX or CLOSE. If the task issues 
any macro instruction which references 
another page, the read interlock is 
released. A page level write interlock is 
released by the GET, type-KY READ, RELEX , 
WRITE, DELREC, or CLOSE macro instruction 
or by any macro instruction which 



The SDST interlock is a one byte field 
at the beginning of the SDST control entry. 
While that lock is set, no other task may 
access the SDST* Within the SDST, data set 
and member entries are made to record the 
allocation of shared storage. The Search 
SDST routine, which makes the SDST entry, 
does not allocate the shared storage, but 
simply reserves space in the SDST for the 
allocation to be recorded. The reserved 
space must be interlocked to prevent system 
usage of the SDST entry before the alloca- 
tion is actually completed. This is done 
by setting the SPT number to X'FFFF 1 , which 
is an invalid SPT number. After allocation 
of shared storage, the routine obtaining 
the shared virtual storage will store the 
actual SPT number in the SDST, thus releas- 
ing the pseudo-lock. 

The RESTBL interlock must be set by 
those routines manipulating the RESTBL of 
shared data sets. This includes most of 
the VAM modules. The RESTBL interlock is 
the first byte of the RESTBL header, and 
has the same effect as a conventional write 
interlock. Most VAM routines can be called 
at a variety of levels; that is, when a 
routine is called that may manipulate the 
RESTBL, the interlock may or may not alrea- 
dy be set. For this reason, each routine 
attempts to set the lock. If the lock is 
already set, the tasks must wait until it 
is reset, unless it was set by the current 
task against the current DCB. This infor- 
mation is in the RESTBL. The ID of the 
task imposing the RESTBL lock is recorded 
in the RESTBL header CRHDTID), and the 
interlocks charged against a DCB are rec- 
orded in the DCB header. 

As with setting the RESTBL lock, each 
routine which attempted to set the lock 
must attempt to reset it, but only the rou- 
tine which actually set the lock will 
effect its release. This is accomplished 
by storing, in the RESTBL header, the PSECT 
location of the routine which caused the 
lock to be set. When backing out of a nest 
of calls, each routine will attempt to 
reset the RESTBL lock, but if it did not 
set it, a return is made to the next higher 
level with the interlock still in force. 
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Sharing of virtual organization data 
sets is dependent upon the owner permit-ting 
the sharing by means of the PERMIT command 
and the user declaring his intention to 
share the data set by means of the SHARE 
command. The command system routines and 
catalog service routines set indicators in 
the ovmer's catalog which indicate his wil- 
lingness to share the data set, the users 
with whom he is willing to share it, and 
the access to the data set he wishes each 
to have. These routines also set indica- 
tors in the user's catalog which associate 
the data set name he is using with the 
owner's data set. 



Three routines in th 
provide the additional 
to facilitate the shari 
The first two of these 
CCZCOH) and Release Int 
maintain interlocks in 
the system. These inte 
users from simultaneous 
set. 



e access methods 
processing required 
ng of data sets. 
routines. Interlock 
erlock (CZCOI), 
various tables in 
rlocks prevent two 
ly updating a data 



set, the task attempting to set a write 
interlock will wait until all read inter- 
locks have been removed by the tasks that 
set them. No additional read interlocks 
will be set during this wait. (See Chart 
LA. ) 

Restrict ions ; It is impossible to impose 
more than 2 55 read interlocks with this 
routine. 

Attributes : Read-only, reenterable, privi- 
leged, public, system. 

Entry Point : CZCOH1 — Entered via type-1 

linkage. 

Input : Register 1 contains the address of 
the following parameter list: 

Word 1 — Address of the interlock control 
word. 

Word 2 — Address of the type code specify- 
ing the interlock to be set. 



The third of these routines is the 
Search SDST routine (CZCQE) . This routine 
searches the shared data set table in an 
effort to locate the name of a shared data 
set or member of a shared partitioned data 
set. This table consists of a group of 
chained data set or member entries, which 
correlate opened data sets or members with 
their respective shared page tables. These 
shared page tables, in turn, specify the 
location of each page of the data set in 
main storage, and are followed by the 
external shared page tables, which list the 
external storage addresses of the data set 
pages. 

If a data set is not already listed, 
this routine will create an entry for it; 
if the data set is listed, the count of 
users sharing it is incremented. This rou- 
tine is also used to delete entries or 
decrement the count of users sharing the 
data set, as each user closes his DCB asso- 
ciated with the data set. A description of 
Search SDST is included in the preceding 
section. 

Interlock Routine CCZCOH) 

Interlock is called by other system rou- 
tines to impose read CR) or write CW) 
interlocks on an interlock control word. 
The type of interlock set depends upon the 
OPEN option. Tables 34, 35, and 36 sum- 
marize the effects of these options on the 
operation of Interlock. The interlock con- 
trol words are used to control shared 
access to the POD, RESTBL (header or 
external page entries) # member headers, and 
SDST data set entries. When a write inter- 
lock is imposed, no additional read inter- 
locks may be set. If a read interlock is 



Word 3 — ■ Address of the DCB associated 
with the data set on which the lock is 
being imposed. 

The type code pointed to by word 2 is a 
2*~ byte field described as follows: 

Byte 1 specifies the type of interlock to 
be reset: 

CR' = Read 
c i W t = write 

Byte 2 specifies the table in which the 
interlock is to be reset: 

X^OO 1 = SDST 

X s OV = RESTBL 

X'08 1 = POD 

X'OC* = Member Header 

X^O' = External Page 

The DCB address normally specified in 
word 3 may be set to zero if it is not 
known. However, during the time that an 
interlock remains imposed after no DCB 
address was specified, it must be assured 
that the system will not ABEND. 

Modules Called : 

TSEND CCEAP9) — End this task's time slice 

while waiting for a lock to be reset by 
another task. 

SYSER CCEAIS2) -- Report' invalid parameters 
as input. 

ABEND CCZACP1) -- Terminate task after 
SYSER. 

XTRCT CCEAH03) — Get task ID for RESTBL 
header area. 
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Exit s; 

Nomwi -- Exit is to the calling routine 
with the specified interlock set- No 
completion code is given. 

Errors -- The type codes supplied arc 
checked for validity and a SYSER and 
ABEND are given if either is invalid. 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for the CSECT and PSECT, para- 
meter list, DCB, DCB header, interlock word 
and type codes. 

The interlock type and the table type 
where the interlock is to be imposed are 

tested for validity. 



The write interlock 
lock word is tested to 
interlock is already i 
write interlock is on 
not for a RESTBL lock, 
forced by calling TSEN 
tasks to continue proc 
release the interlock 
was attempting to set 



byte of the inter- 
determine if a write 
n force. If the 
and the request is 
time slice end is 
D. This allows other 
essing and eventually 
that the current task 



The RESTBL lock is handled slightly dif- 
ferent from other interlocks. Each routine 
which manipulates the RESTBL attempts to 
set a write interlock on the RESTBL, which 
is accounted for on a DCB within task 
basis. A call to the interlock routine may 
be executed for a RESTBL interlock and the 
KESTBL may already be locked. If this con- 
dition occurs and the same task which set 
the initial lock is attempting to set 
another against the same DCB, control is 
returned to the caller , as if the lock had 
just been set. Otherwise, TSEND is called. 

If the write interlock byte of the 
interlock is not set, interlocks may be set 
as desired. The locks will be recorded in 
the interlock summary word of the asso- 
ciated DCB header. In addition, if the 
lock is set on the RESTBL, the virtual 
storage address of the PSECT of the calling 
routine is saved in the interlock word, and 
is used in the interlock reset process. 

The interlock to be set is either read 
or write. The write lock which is already 
set is recorded in the DCB header, and con- 
trol is returned to the caller by the 
RETURN macro instruction if no read locks 
are currently set. Otherwise, TSEND is 
called to wait for the read locks to be 
released. 

Read locks are set cumulatively. The 
read interlock is set and the read inter- 
lock counter is incremented to indicate the 
presence of one or more read interlocks. 
This read interlock process is controlled 



by an additional lock byte within the 
interlock word itself. The write lock is 
reset, the read lock is accounted for in 
the DCB header, and control is i et \u ned to 
the caller by the RKTUKN nwno instruction. 



Release Interlock Routine (CZCOl) 

Release Interlock (RLINTLK) is called by 
system routines to release read (R) and 
write (W) interlocks on an interlock con- 
trol word. (See Chart LB. 3 

Attributes : Read-only, reenterable, privi- 
leged, public, system. 

Entry Point : CZCOI1 — • Entered via type-1 
linkage. 

Input : Register 1 contains the address of 
a 3-word parameter list as follows: 

Word 1 -- Address of interlock word. 

Word 2 -- Address of the type interlock. 

word 3 -- Address of DCB being processed. 

The type of interlock pointed to by word 
2 of the parameter list is a 2-byte field 
described as follows: 

Byte i specifies the type of interlock to 
be reset. 

C f R' = Read 
C f W = Write 

Byte 2 specifies the table in which the 
interlock is to be reset: 

X'OO' = SDST 
X'OU* = RESTBL 

x^os* = POD 

X'OC ^Member Header 

X'lO" = External Page 

The DCB address normally specified in 
word 3 of the parameter list may be set to 

zero, if it is not known. it should be 
known, if it was known at the time the lock 
was set. If it is not specified the inter- 
lock summary bits in the DCB header will 
not be reset. 

Modules Called : 

TSEND (CEAP9) — End time slice while wait- 

ing for a lock to be reset by another 

task. 

SYSER (CEAIS2) — Invalid input to CZCOl . 

ABEND (CZACP1) — Terminate task after 
SYSER. 

VDMEP (CZCQK) — When desired lock to be 
set is not set. 
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Exits : 

Normal -~ Exit is to the calling routine by 
the RETURN macro instruction. No com- 
pletion code is given. 

Error — The type codes are checked for 

validity and SYSER and ABEND are called 
if either is invalid. 

VDMEP is called if an attempt is made to 
release a lock that is not set. 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for CSECT and PSECT, parameter 
list, DCB, DCB header, interlock word and 
type codes. 

If the table type code specified is 
invalid, SYSER is called. Also, if the DCB 
is specified, and the summary bit in the 
DCB header corresponding to the interlock 
intended to be released does not indicate 
that the lock is on, VDMEP is called. 

A release request may be for a read or a 
write interlock. A special case of this is 
the RESTBL interlock. The RESTBL interlock 
must be set and must be released by the 



same routine that set it. The PSECT 
address of the routine requesting reset is 
compared to the PSECT address stored in the 
interlock word. If they are the same, the 
lock is reset and control is returned to 
the caller by the return macro instruction. 
Otherwise the lock is not reset before 
returning . 



A request to release a write interlock 
will cause the interlock to be reset. If 
the DCB is specified and the summary does 
not indicate that the requested lock is 
set, SYSER is called. If the summary does 
include the requested lock, the bit is 
cleared and control is returned to the 
caller by the RETURN macro instruction. 

Read interlocks are released by decre- 
menting the read interlock counter. When 
the counter goes to zero, the physical and 
read interlock is cleared. 

The manipulation of the read interlock 
and the read interlock counter are con- 
trolled by an additional lock in the inter- 
lock word. The control lock is reset and 
the summary bits are reset if a DCB was 
specified. 
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SECTION U ; 



OPEN AND CLOSE PROCESSING 



This section describes the routines 

which prepare a data set and its related 
control blocks for processing (OPEN) and 
routines which remove a task s s refeiences 
to a data set and release unneeded space 
when a task no longer wishes to reference 
the data set (CLOSE) - The routines in this 
section can be entered as a result of one 
oi seven macro instructions being issued: 



OPENVAM Routine (CZCOA) 

OPENVAM is called by Open Common CCZCLA) 
to perform DCU and data set initialization 
common to all of the virtual access 
methods. (See Chart MA.) 



Att ributes : closed, reentrant, privileged. 



OPEN — a user wishes to access or 
create a data set. 



2. DUPOPEN ■ — a user wishes to access or 

create a duplexed data set* 

3. FIND — a user wishes to access a 
member of a partitioned data set, 

<*. CLOSE — a user has finished using a 
data set* 



Entry Point : CZC0A1 -- Entered via type-1 
linkage. 

Input : Register 1 contains a pointer to a 
four word parameter list as follows: 

Word 1 — Address of the DCB. 

Word 2 — Address of the JFCB. 

Word 3 -- Address of "Fence Straddler* save 
area. 



DOPCLOSE ■ — a user has finished using 
a duplexed data set. 

STOW --a user has finished using a 
member of a partitioned data set, 

ABEND — a task is being abnormally 
terminated and its data sets must be 
closed. 



Word 4 — Address of the public or private 
volume table (PVT). 

Modules Called : 

Connect (CZCG7) — Connect task to shared 
RESTBL 

ESA Lock (CZCEJ1) -- Lock PAT, (CZCEJ2) -- 
Unlock PAT. 



Figures 22 and 2 3 depict the interaction 
among the various modules involved in open- 
ing and closing a data set. The routines 
Open Common CCZCLA) and Close Common 
CCZCLB) contain the initial point of link- 
age from the OPEN and CLOSE macro instruc- 
tions for all access methods and have been 
described earlier in this manual. 

Also included in this section is a 
description of the VAM ABEND Interlock 
Release routine. When a task is abnormally 
terminated because of some error condition, 
the close processing is performed to close 
any data sets that the task may have been 
using. The VAM ABEND Interlock Release 
routine is called to locate and to release 
any interlocks which were set when the 
ABEND was issued. 



REQPAGE (CZC0E1) — Assign directory page 
CVPAM) . 

RELEXPG CCZCEN1) — Release pages, 

DELCAT CCZCFD1) -- Release catalog entry. 

FREEMAIN (CZCGA3) « Free virtual storage. 

Search SDST CCZCQE1) — - Creates a shared 
data set table entry for a newly opened 
data set or increments the count of 
users for the data set if it is already 
open. 

Interlock (CZC0H1) -- Interlocks the RESTBL 
of a shared data set when the routine is 
operating on it. 

Release Interlock (CZC0I1) -~ Releases the 
RESTBL interlocks placed on shared 
RESTBLs . 



OPEN PROCESSING 

The routines associated with Open pro- 
cessing include OPENVAM, DUPOPEN, VSAM 
Open, and VISAM Open. 



DSCB READ/WRIT (CZCEM1) — Request a PAT 
write. 

VDMEP CCZCQK1) — Issue diagnostic message 
and terminate function but not task. 
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Figure 22. Module Interaction in VAM Open Processing 
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Figure 23. Module Interaction in VAM Close Processing 
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DSCB RECOVU^x xCZCEFi) -- Attempts to reco- 
ver from an error when the DSCB Is read. 

GETKAIN CCZCG2/ -- Obtains virtual storage 
for nonshared EESTBLs and for required 
directory pages for nonshared data sets. 

GETSMAIN CCZCG6) -~ Obtains shared virtual 
storage for shared RESTBLs. 

FIdDEXPG (CZCEL1) -- - Assigns external 
storage space to a new data set* 

WR'XTDSCB CCZCEW1) -- Writes out updated 
DSCBs to the volume. 

CKCLS CCEAH24) — Obtains the protection 
class of the task, 

XTRCT (CEAH0 3) — - Obtains the ID of the 

task. 

Expand RESTBL (CZCQI1) — Increases the 

s„ze of the nonshared RESTBL when neces- 
sary to contain new headers, 

r»K>VEPAGE (CZCDC1) — Reads in the directory 
pages of a partitioned or indexed 
sequential data set. 

VSAM OPEN CCZCOP1) — Performs open proces- 
sing unique to sequential data sets, 

VISAW OPEN CCZCPZ1) — Performs open pro- 
cessing unique to indexed sequential 
data sets. 



Exits: 

Normal — - Return to calling routine. 

Error -- VDMEP is called under the follow- 
ing conditions: 

« Error encountered trying to PGOUT 
updated DSCB. 

• DSCB has invalid chain field. 

• Attempt to expand shared data set. 

• Relative volume number is out of 
volume table limit* 

» Bad return code from CZCEM; failure to 
read DSCB, 

• An attempt to open a non-VAM data set. 

• Search SDST could not link to shared 
VM. 

• Should be E-type DSCB but is not, 

• Total pages used by data set in error. 

» External page request exceeds amount 

available. 



• Attempt to open new data set for 
read-only. 

• Two active users using private shared 
data set, 

• Unrecoverable DSCB error. 

• DSCB does not contain collect number 

of extents . 

Operation : On entry, OPENVAM saves all 
input registers and establishes base regis- 
ters for the CSECT, PSECT, RESTBL, DCB, and 
JFCB. The user's authorization to open the 
data set and the data set organization are 
checked. If the user is not authorized to 
open the data set or if the data set is not 
VAM, VDMEP is called. 

Two types of data sets are processed by 
OPENVAM # shared and nonshared. While the 
objective of OPENVAM is functionally simi- 
lar for both types , that is, to prepare 
data sets for access, they are handled dif- 
ferently. The logic flow of OPENVAM 
diverges at specific points to accomplish 
processing for shared or nonshared data 
sets . 

One of the functions performed by OPEN- 
VAM is to build a RJESTBL for a new data 
set. Tests are made to see if the data set 
has already been opened. If the data set 
has been opened, a RESTBL already exists 
and this processing can be skipped. The 
tests for opened DCBs differ for shared and 
nonshared data sets. If the data set is 
shared, the task currently opening the data 
set may have opened it. In this case, the 
count of open DCBs in the JFCB is nonzero. 
If another task has opened the data set, an 
entry will exist in the shared data set 
table. 

A call ^is made to Search SDST CCZCQE) to 
locate or to create an entry. Two return 
codes from CZCQE are acceptable. One code 

indicates that an entry existed. In this 
case, a call is made to Connect CCZCG7) to 

connect the task to the shared RESTBL which 
exists. The second code indicates that no 
entry existed but one was created. In this 
case, the RESTBL must be created since the 
data set is newly opened. Any return code 
other than these two is considered an error 
and VDMEP is called. 

If the task currently opening the data 
set had DCBs already open for it or if the 
task was connected to the shared RESTBL, 
the following processing to create the 
RESTBL is skipped. 

For nonshared data sets, the test 
involves a check of the JFCB to see if the 
count of open DCBs is nonzero. The same 
criteria apply to nonshared data sets as to 
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shared. 

built. 



If DCBs are open, no new RESTBL is 



Building t he RESTBL: For all new] y opened 
old data sets, the format -E DSCB j :; read 
into virtual storage. This is accompli shed 
oy means ot the SETXP macro instruction 
which simply adcis the external page number 
to the externa] page table for th»* task. 
Any reference to the DSCB page will result 
in a paging operation by the resident 
supervisor. Once the DSCB page is, in vir- 
tual storage it is checked for errors. A 
cnecksum error results in a call to DSCB 
Recovery (CZCEF) to attempt recovery. A 
bad volume pointer, a pointer to a non-DSCB 
page, a bad relative page number for a 
device, or the case where data set names in 
the JFCB and the DSCB do not match, result 
in a VDMLP call. 

Once the format- E DSCB has b^en read in, 
the number of pages required to contain the 
RESTBL is computed. For new data sets, 
this number is a function of the primary 
space allocation as indicated in the JFCB. 
For existing data sets it is a function of 
the size of the data set as it exists. If 
the data set is shared, this RESTBL size is 
increased by 2 pages. If the data set is 
SYSLIB, 10 pages are added; for SYSCAT, 5 
pages are added. This increment is used 
because a shared RESTBL cannot be expanded 
and the value 2 represents a "best guess" 
of the ultimate size of the RESTBL. The 
value should be adjusted as installation 
needs dictate. If the shared data set is 
also index sequential, an additional 2 
pages are used. 

After the RESTBL size has been computed, 
a call is made to GETMAIN or to GETSMAIN to 
obtain virtual storage for the RESTBL. 
When virtual storage has been obtained for 
the RESTBL, it is interlocked, if shared, 
and the RESTBL is filled in. This process 
starts with the building of the RESTBL 
header. The total number of pages is 
stored; if the data set is not new the 
counts of overflow, directory, and data 
pages are stored, and, for all data sets, 
the number of assigned pages is compared to 
the number of "in use" pages. If more 
pages are in use than are assigned, VDMEP 
is called. If no error exists, the RESTBL 
is chained to the JFCB and pointers to the 
format- E DSCB and the volume table are 
placed in the RESTBL. 

Next, the data set is checked to see if 
it is new. If so, a call is made to FIN- 
DEXPG (CZCEL) to get external pages for 
assignment to the data set, and the pages 
returned are placed in the RESTBL and 
marked assigned but not in use. A call is 
later made to WRITDSCB (CZCEW) to place the 
updated entries in the DSCB chain. If an 
error return is received from FINDEXPG, 



VDMEP is called. For existing data sets, a 
test is made to see if the volume is public 
or private. In the case of private 
volumes, a list of private volumes is con- 
tained in the DSCBs before the page 
entries; these volume IDs must be skipped 
and are« not placed in the RESTBL. For 
existing data sets, the calls to FINDEXPG 
and WRITE»SCB are not required. 

When the external page entries from the 
DSCB, or for new data sets from the FIN- 
DEXPG routine, are placed in the RESTBL, a 
distinction is made between shared and non- 
shared data sets. For nonshared, the 
entries are simply moved into the RESTBL. 
For shared data sets, an interlock word 
must be provided before each page entry. 
This interlock word is inserted and set to 
zero as each entry is placed in the RESTBL. 

When the RESTBL has been built, the DCB 
header must be built and added to the chain 
of headers in the RESTBL. This last step 
is performed first. The available space in 
the RESTBL is checked to see if there is 
space to contain the new header. If no 
space is available, a call is made to 
Expand RESTBL to increase the size of the 
RESTBL. This is only done for nonshared 
data sets. If the condition occurs for a 
shared data set, a call is made to VDMEP. 
when space has been found to contain the 
header, it is chained to the list of head- 
ers in the RESTBL and the DCB header is 
then built. 

Building tne DCB header involves chain- 
ing it to the DCB, the RESTBL, the RESTBL 
header, and the JFCB. The protection class 
of the task is determined by a call to 
CKCLS (CEAQ4), and the task ID by a call to 
XTRCT (CEAH2); these values are stored in 
the DCB header. The VAM read-only flag in 
the JFCB, if turned on by Common Open, will 
be turned off and the read-only access flag 
turned on in the DCB header. Finally, the 
address of the directory or the POD is 
placed in the DCB header. 

If the data set is shared, there are no 
other DCBs open, and the data set is either 
partitioned or index sequential, it may be 
necessary to assign directory pages. If no 
directory pages exist for the data set, a 
call is made to Request Page (CZCOE) to 
assign the first page as a directory page. 
After this or if directory pages existed, a 
call is made to MOVEPAGE to read the direc- 
tory pages into virtual storage, and the 
number of directory pages is placed in the 
RESTBL. Next, or if the data set was par- 
titioned or sequential, or if the data set 
was already opened, the access dependent 
open routine is called as described below. 

For nonshared data sets the processing 
is essentially the same with two excep- 
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lions- First, a call is made to GETMAIN 
tor virtual storage space prior to the call 
to MOV EP AGE. This is done to provide space 
for the directory pages. Second, the count 

of directory pages is not updated in the 
RESTBL and the access dependent open rou- 
tines are called. 

Acce ss-Dependent Open Processing : The data 
set is now tested to determine its organi- 
zation* if the data set is sequential g 
VSAM OPEN (CZCOP) is called; if it is index 

sequential, VISAK OPEN (CZCPZ) is called. 
These routines perform open processing 
unique to the data set organization- If 
the data set is partitioned* a member head- 
er is built and added to the chain of memb- 
er headers in the RESTBL. This is done in 
the same manner as the adding of the DCB 
header with the call to Expand RESTBL for 
nonshared data sets, when necessary, and 
the call to ABEND when the RESTBL cannot 
contain the header for a shared data set. 
Once the member header has been built t it 
is linked to the DCB header, the RESTBL 
interlock is released, if the data set is 
shared, and control is returned to the cal- 
ling routine. 



Word 2 — Address of the secondary DCB. 

Word 3 — Address of an option byte which 
contains : 



bits 0-3 


Not US 


bits «4-7: 




0000 


Input 


1111 


Output 


0001 


Read Back 


0011 


Inout 


0111 


Out in 


0100 


Update 


Modules Called: 





OPEN COMMON CCZCLAO) -- A single call is 

made to open both the primary and secon- 
dary DCBs* 



SYSER CCEAIS2) 
message. 



Minor system error with 



ABEND CCZACP1) — Abnormal task termina- 
t ion - 

FINDJFCB CCZAEB) -- To create a JFCB when 
one is not found for the DCB being dup- 
licated OPEN. 



DUPOPEN Routine CCZCEY) 

The function of DUPOPEN is to open dupl- 
icate data control blocks for a duplexed 
data set residing on public volumes. One 
copy of the data set is the primary copy. 
The secondary copy resides on a separate 
public device and is r at all times, an 
exact copy of the primary copy* As such, 
the secondary copy can be used for recovery 
purposes when a read error occurs on the 
primary copy, 

DUPOPEN flags the JFCBs CTDTDC1) to ind- 
icate the primary and secondary copies, and 
chains the two JFCBs by placing f in each 
JFCB, a pointer to the other CTDTDUP). By 

calling Open Common and, subsequently 9 
OPENVAM, DUPOPEN builds a RESTBL for each 
copy of the data set and opens the DCBs. 
The address of each RESTBL is placed in its 

corresponding DCB and the field DHDDUP of 
each DCB header is set to point to the 
other RESTBL. (See Chart MB.) 

Att ributes : Closed, fetch protected, pri- 
vileged, reentrant, nonrecursive, and 

residing in public virtual storage. 

En try Point : CZCEY1 -- DUPOPEN is entered 
by a type-1 or type-2 linkage generated by 
the expansion of the DUPOPEN macro 
instruction. 

[nput ; Register 1 contains the address of 



the following parameter list: 

Word 1 -- Address of the primary DCB. 



Exits: 

Normal — Return to the calling routine. 

Error ~ ABEND is called under the follow- 
ing conditions: 

• No JFCB could be found or created for 
the primary or secondary DCBs. 

• Data set not public. 

• DCBs not compatible* 

• Data set not VAM organization. 

• Same JFCB specified for both DCBs. 

• JFCB specified has been found in 
JOBLIB. 

SYSER is called before each ABEND. 

Operation : When DUPOPEN is entered , 
register 1 contains a pointer to a paramet- 
er list which, in turn, contains pointers 
to the primary and secondary DCBs. DUPO- 
PEN, after performing the 1 usual register 
save and base register initialization, 
saves the addresses of these DCBs and the 
open option in its own PSECT, DUPOPEN then 
begins to scan the list of JFCBs in the TDT 
beginning with the last JFCB created and 
working back toward the first. 

For each JFCB it encounters, it compares 
the data set name in the JFCB with that in 
the DCB. If no matching JFCB is found in 
the entire list of JFCBs, FINDJFCB is 
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called to help create one. When the JFCB 
for the first DCB is found, its address is 
saved and the same procedure is repeated 
for the second DCB. 

When both JFCBs have been located and 
tested to ensure they are not the same 
JFCB, they are examined to ensure that the 
corresponding data sets are on public 
storage and are VAM organization. If eith- 
er data set fails either test, the task is 
terminated and is sent the appropriate 
error message. 

A test is made to ensure that the DCB is 
not already in the user's JOBLIB. 

Next, a test is made to see if any DCBs 
have been opened for the data set* If none 
has, the JFCBs are chained together and a 
flag is set in each to indicate which is 
the primary and which is the secondary. 
When this is done or if some DCB had alrea- 
dy been opened for this data set, a para- 
meter list is constructed for OPEN COMMON. 
This parameter list contains the addresses 
of both DCBs and the open option indicator. 
OPEN COMMON is then called to open both 
DCBs and is passed the address of the para- 
meter list. 

On return, the two new DCBs are compared 
to ensure that they match. If they do not 
match, ABEND is called and a message is 
sent to the task. If the DCBs do match, 
DUPOPEN links the corresponding RESTBLs and 
returns to the caller. 

VSAM Open Routine CCZCOP) 

VSAM Open is called by OPENVAM (C2COA) 
and by FIND (CZCOJ) to initialize the data 
set buffers and the DCB to allow processing 
of a virtual sequential access method 
CVSAM) data set (See Chart MC.) 

Attributes : Read-only, reenterable, privi- 
leged, public. 

Entry Point : CZCOP1 — Entered via type-1 
linkage. 

Input ; Register 1 contains the address of 
the DCB to be opened. 

Modules Called ; 

GETMAIN CCZCG2) — Obtain virtual storage 

space for the sequential buffer to be 

associated with this DCB. 

SETL (CZCOT1) — Initialize data set to 
begin processing at beginning or end. 

Exits : 

Normal — Return to the calling routine. 

Error — VDMEP is called under the follow- 
ing conditions: 



• Record length is specified greater 
than 1 segment (1,0*48,576 bytes). 

• Record format code is in error, that 
is, not 'V , ' E* or 'IT . 

• Record format is undefined, and record 
length is not a multiple of 4096 
bytes . 

Operation : General registers are stored in 
conformance with linkage conventions and 
base registers are declared for the PSECT 
and CSECT, a DCB # DCB header and a RESTBL. 

The V-cons for the sequential user 
macros GET, PUT, PUTX, and SETL are stored 
in the DCB. These sequential routines are 
•fence sitters." Their PSECTS cannot be 
used for storage (save areas) , therefore, 
save areas are allocated dynamically. Open 
Common gets a "scratch" page for this pur- 
pose and its location is stored in the GET 
R-con location in the DCB by OPENVAM. VSAM 
Open takes that value, computes save area 
locations for the other macros and stores 
the computed values in the respective R-con 
locations in the DCB. 

VSAM Open is responsible for establish- 
ing input/output areas in virtual storage 
for the sequential access method. The 
space requirement is computed from the log- 
ical record length declared in the DCB 
(DCBLRE) at OPEN time. The maximum allow- 
able record length is 1,048,576 bytes CI 
segment); if this value is exceeded, ABEND 
is called to terminate the task. 

The sequential access method processes 
three types of record format - fixed, vari- 
able and undefined. Special considerations 
are applied to each format in the alloca- 
tion of I/O space. 

Undefined records must have page- 
multiple record length. ABEND is called if 
the record length (DCBLRE) is not in page 
multiples. 

Variable-length records have eight bytes 
of space control information appended to 
each record (four bytes preceding the reco- 
rd, provided by the user, and four bytes 
following, provided by VSAM) . This 
adjusted value record length plus control 
bytes is used to compute the actual amount 
of storage required. 

For fixed- length records whose record 
length is a page, only one I/O page is 
needed. 

For variable- length and fixed- length 
records other than page multiples, a mini- 
mum of two I/O pages is required. GETMAIN 
is called by the GETMAIN macro to obtain 
the virtual storage to be used as I/O 
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areas. The virtual storage location of 
this area is stored in the DCB and the DCB 

header. 

The record length (DCBURE) is saved in 
the DCB header (DHDMRL) as the maximum log- 
ical record length. If this value is ever 
exceeded, and the condition can be 
detected, ABEND will be called* This could 
happen while processing undefined or 
variable-length records where the record 
length is defined dynamically by the iser. 

VSAM Open is also responsible for the 
initial positioning of the data set. A 
call is made to SETL CCZCOT) to set DCBLPA 
to the appropriate value. The DCB open 
option CDCB0P1) is used to determine what 
that value should be. For input , update, 
or INGOT, the data set is logically posi- 
tioned to the beginning* For output or 
OUTIN the data set is positioned to the 
logical end. 

Control is returned to the caller by the 
RETURN macro. 



VISAM Open Routine (CZCPZ) 

V15AM Open is called by VAM general sex- 
vices Open and by Find, to initialize DCB 
and page buffers. CSee Chart MD. ) 



Attributes : Read-only f reenterable , publ- 
ic, privileged. 

Entry Point : CZCPZ1 -- Entry to VISAM Open 
is by type-1 linkage (privileged to 
privileged) . 

Input ; Register 1 contains the address "of 

the DCB. 

Modules Called ; 

GETMAIN (C2CGA2) — Obtain page buffers for 
data and overflow pages. 

SETL CCZCPC2) — Position data set accord- 
ing to OPEN option. 

Exits: 

Normal — Return to the calling routine. 

Error — ABEND is called if key offset * 
key length is greater than record 
length* VDMEP is called under any of 
the following conditions: 

• Key length is less than the minimum. 

• Record length exceeds maximum, 

• Key offset goes beyond record. 

• Overflow pages greater than 2*40 f or 
directory pages greater than 255. 



® Data set opened for input or Inout and 
no data pages. 

Operation s General registers are stored in 
conformance with linkage conventions, and 

base registers are declared for the CSECT 
and PSECT, a DCB, DCB header and a RESTBL. 

The V-cons far the index sequential user 
macros GET, PUT, and SETL are stored in the 
DCB. These index sequential routines are 
"fence sitters." Their PSECTS cannot be 
used for storage (save areas), therefore* 
save areas are allocated dynamically on a 
DCB basis- Open Common gets a "scratch" 
page for this purpose, and its location is 
stored in the GET R-con location by OPEN- 
VAM. VISAM Open takes that value, computes 
save area locations for the other macros 
and stores the computed values in the 
respective R-con locations in the DCB. The 
PUTX macro is not used by VISAM Open. Its 
R-cons and V-cons are zeroed to prevent any 
erroneous usage. 

Legality checks are made on DCB 
information- key lengtli CDCBKEY) , record 
length CDCBLRE), and relative key position 
CDCBRKPK 

The minimum key length is one byte. 

The maximum logical record length of a 
VISAM data set is 4000 bytes. 

The origin of the relative key position 
must be within the range of the logical 
record length. Also, the relative key 
position plus the key length must not 
exceed the logical record length. 

DCB fields peculiar to VISAM are 
initialized. 

Data records may never cross page boun- 
daries in index sequential organization, 
therefore, only one virtual storage page is 
required as an I/O buffer. This is 
obtained by the GETMAIN macro. 

Where this is not the first DCB open for 
a nonshared data set within the same task, 
the DCB will be linked to the existing page 
buffer, and no call to GETMAIN is 
necessary. 

If overflow pages exist, a virtual 
storage page is also needed as an overflow 
page I/O jbuffer. The maximum number of 
overflow pages is 240. 

Having obtained all necessary virtual 
storage space, VISAM Open will logically 
position existing data sets (that is, 
RHDDAT-0). A nonexistent data set may not 
be opened for input, update or inout OPEN 
options. If there are no data pages, VISAM 
Open returns to the caller by the RETURN 
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macro. If the data set has data pages, a 
SETL (CZCPC) is executed as defined by the 
OPEN option. Input, update and inout cause 
a SETL to the beginning of the data set. 
Output and outin cause a SETL to the end of 
the data set. Control is then returned to 
the caller by the RETURN macro. 



Search SDST (CZCQE) — Deletes the shared 
data set table entry for the task clos- 
ing the DCB. 

VSAM Close CC2COQ) — Performs close func- 
tions unique to sequentially organized 
data sets. 



CLOSE PROCESSING 

The Close routines consist of CLOSEVAM, 
DUPCLOSE, VSAM Close , VIS AH Close, and VAM 
ABEND Interlock Release. 



VISAM Close (CZCQA) — Performs close func- 
tions unique to indexed sequentially 
organized data sets. 

Stow CCZCOK) -~ Stows a member of a parti- 
tioned data set and calls the appropri- 
ate access dependent close routine. 



CLOSEVAH Routine CCZCOB) 

CLOSEVAM is called by Close Common or by 
DUPCLOSE to perform close processing for a 
given DCB. It may also be called by ABEND 
to close the DCB for a task which is being 
abnormally terminated or by VDMEP if a 
function (but not the task) is being ter- 
minated. The major functions of CLOSEVAM 
are to: 

• Delete only the DCB header for data 
sets which have other DCBs open, 

• Release assigned but not used external 
pages of the data set by calling 
RELEXPG. This step is omitted if the 
HOLD option has been specified. 

• Update the DSCBs on the volume by cal- 
ling WRITDSCB. 

• On the close of the last DCB open for 
the data set, the RESTBL and, if the 
data is partitioned, the POD are 
deleted by calling FREEMAIN. 

• Delete the data set, its catalog entry, 

and its JFCB if "delete at close" is 
specified. This is accomplished by 
calling DELVAM. 

• If the data set resides on a private 
volume and the last open DCB is being 
closed, the volume table is deleted by 
calling FREEMAIN. (See Chart ME.) 

Restrictions : CLOSEVAM may not be called 
if the specified DCB is not open. 

Entry Points ; 

CZC0B1 — Normal entry via type-1 linkage. 

CZCOB2 — Direct entry from close command. 

Input : Register 1 contains the address of 
the DCB being closed. 

Modules Called : 

Interlock CCZCOH) — Interlocks the RESTBL 
for shared data sets. 



MOVEPAGE (CZCOC) — Writes out the POD when 
required. 

RELEXPG (CZCEN) « Releases unused data set 
pages when the data set is closed. 

DSCB READ/WRIT CCZCEM) -- Read in and write 
out a format- E DSCB. 

ESA LOCK CCZCEJ) -- Lock and unlock the 

PAT. 

DELVAM CCZCFT) — Deletes a data set, its 
catalog entry* and the associated JFCB 
when the "delete at close" option is 
specified and the DCB being closed is 
the last one open for the data set. 

WRITDSCB CCZCEW) — Updates the DSCBs on 
the volume when required. 

FREEMAIN (CZCGA) — Releases virtual 

storage occupied by the RESTBL, directo- 
ry pages, and buffer pages. 

Release Interlock (CZCOI) — Releases the 
interlock on the RESTBL for shared data 
sets which still have DCBs open against 
them. 

Disconnect CCZCG8) -- Disconnects the task 
from the shared RESTBL. 

SYSER CCEA1S) — Declares system errors as 
listed under "Exits". 

ABEND CCZACP) — Abnormally terminates a 
task under the same error conditions as 

for SYSER. 

Exits : 

Normal -- Return to the calling routine. 

Error — SYSER, then ABEND is called under 
any of the following conditions: 

• Search SDST cannot find data set 

entry. 

• Data set being closed is neither 
sequential, indexed sequential, nor 
partitioned. 
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• Error return from Stow. 

» HOVEPAGE unable to write out updated 

POD. 

• DELVAM unable to delete a data set and 
its catalog entry* 

• DSCB Read/Writ unable to read or write 
DSCB. 

Operat ion : For entry at CZCOB1: On entry, 
CLOSEVAM saves the input registers and 
establishes base registers for the CSECT, 
PSECT, JFCB f DCB, RESTBL, DCB header, and 
member header. If the data set is shared, 
the RESTBL is interlocked by calling 
Interlock* 

When CLOSE (TYPE = T) is specified for a 
VAM data set, only data pages, directory 
pages and DSCBs r where required, are writ- 
ten to external storage* The data set will 
remain open and in the same condition as 
would follow a normal OPEN, 

Nor. partitioned data sets are positioned 
(SETL) according to the original OPEN 
option and data set organization prior to 
the completion of the CLOSE (TYPE = T) . 
When partitioned data sets are processed , a 
5TOW-R is issued against the checked out 
neiabers, as during a normal CLOSE. A FIND 
must be issued by the user if the member is 
to b€- reprocessed. 

if not a TYPE = T f when the data set is 
sequential or index sequential , the corres- 
ponding access dependent close routine is 
called- If the data set is partitioned and 
there is a member still checked out, a call 
is made to STOW to update the POD and to 
close the member by calling the appropriate 
access dependent close routine* If an 
error return is received from STO**» SYSER 
and ABEND are called. 

Following the above processing or if the 
data set is partitioned but has no members 
checked out, a test is conducted to deter- 
mine if the POD must be written out. Four 
conditions must exist for this to occur: 

1. The data set must be partitioned • 

2. There must be directory pages to 
output, 

3. Either the DSCB integrity bit ox the 
POD integrity bit must be set, 

4. The DCB being closed must not repre- 
sent the secondary copy of a duplexed 
data set . 

If all these conditions are met, a call 
is made to MOVEPAGE to output the directo- 
ry. During the testing for these condi- 



tions, a further error test is conducted. 
If the data set does not prove to be 

sequential indexed sequential, or parti- 
tioned , SYSER and ABEND are called. This 
same error exit is taken if MOVEPAGE is not 

successful. 

Closing the Last Open DC B: Following a 
successful cdll to MOVEPAGE or if no call 
is required* it is determined if this is 
the last DCB open for the data set. For 
nonshared data sets this is indicated by a 
zero count of open DCBs in the JFCB. For 
shared data sets this same count must be 
zero and, also, the count of open DCBs for 
ail tasks roust be zero. If one of these 
conditions is met Cthat is f this is the 
last open DCB for the data set) it may be 
necessary to delete the data set or to free 
unused space. If there are available 
unused pages and the HOLD option has not 
been specified, a call is made to RELEXPG 
to release the pages- The parameter list 
to RELEXPG includes the RESTBL external 
page entries representing the unused pages* 
For a shared data set the interlock words 
must be removed from the RESTBL before the 
parameter list can be built. 

Following the call to RELEXPG or if no 
release is performed* the DSCB integrity 
bit is checked to see if the DSCBs must be 
updated. If so, a call is made to WRITDSCB 
to perform the update* After a successful 
call to WRITDSCB or if the DSCBs were not 
updated, buffer space area may be freed as 
described below. 

Final Close Processing : In this case, the 
closing of the last DCB for a data set, the 
final close processing involves the release 
of any buffer or overflow pages and the 
release of directory or POD pages. These 
releases are accomplished by calls to FREE- 
MAIN. FREEMAIN is also called to release 
any existing RESTBL pages. Lastly, the 
RESTBL pointer is cleared from the JFCB, 
the DCB and DCB header are unchained, the 
macro transfer list is cleared from the 
DCB* and then a check of last close for a 
DELVAM call is performed. If the Delete at 
Close flag is set, a call is made to DELVAM 
to delete the data set* its catalog entry, 
and the associated JFCB. If DELVAM returns 
an error code f SYSER and ABEND are called. 

If the Delete flag is not set or delete 
has been performed, the control will now 
return to the caller* 

Other Open DCBs ; When other DCBs are open 
for the data set, either for this task or 

for another task sharing the data set, the 

data set cannot be deleted nor can unused 
data set pages be released. 

if the data set is partitioned and 
linked to a member, the number of users 
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accessing t he member:; is decremented. If 
this number reaches zero, the member header 
is deleted from the chain, the chain is 
updated to account for the deletion, and 
the deleted header space is added to the 
list of available RESTBL space. Following 
this, the DCB header is checked. If it is 
chained, the header chain is updated to 
account for the deletion of the DCB header. 
If the header is not chained,, the In Use 
indicator is cleared. Following either of 
these actions, the DCB address is removed 
from the DCB header. 

Next, the space occupied by the DCB 
header is added to the chain of available 
space in the RESTBL and the DSCB integrity 
oit is tested. If this bit is set, 
WRITDSCB is called to update the DSCBs on 
the volume. After this the final close 
processing is performed. 

For data sets for which there are still 
open DCBs f the final close processing is 
abbreviated. Any existing buffer pages or 
overflow pages are released by calling 
FREEMAIN and the macro transfer list is 
cleared in the DCB. Lastly, for shared 
data sets, DISCONNECT is called to discon- 
nect the task from the shared RESTBL. 
After this or if the data set was not 
shared, control is returned to the caller. 



For entry at CZCOB2 : This entry is from 
the CLOSE command, and is provided to per- 
form cleanup of virtual memory associated 
with a data set and occurs when an unavail- 
able (already unloaded or erroneous) DCB 
cannot itself be closed. The address of 
the DCB header is pointed to in register 1 
on entering CLOSEVAM. CZCOB2 decrements 
the TDTOPN count and normal processing fol- 
lows -- but at no time will a DCB be 
pointed to, and no attempt will be made to 
perform a STOW, output buffers or direc- 
tories § or rewrite DSCBs. 



DUPCLOSE Routine CC2CEZ) 

The function of DUPCLOSE is to close the 
DCBs associated with a duplexed data set by 
means of a call to Close Common.. In addi- 
tion, DUPCLOSE unlinks the RESTBLs for the 
data sets and, for the last DCB open for 
the data set, unlinks the TDTs and clears 
tne duplicate copy indicator. (See Chart 
MF.) 

Attributes : Privileged, fetch protected, 
closed, read only, reentrant, residing in 
public virtual storage. 

Entry Point : CZCEZ1 -- Entered by means of 

a type-1 or a type-2 linkage generated by 

the expansion of the DUPCLOSE macro 
instruction. 



Input : On entry, register one contains the 
address of a two word parameter list: 

Word 1 -- Address of the primary DCB. 

Word 2 — Address of the secondary DCB. 



Module;:-: Called : 

Close Tommon (CZCLB) -- A single call is 

made to close the DCBs and to return the 
virtual storage they occupied. 

SYSER (CEAIS) — Called by means of the 

SYSER SVC when one of the DCBs indicates 
a CSORG other than VhM. 

ABEND (CZACP) — Called to issue a message 
and terminate the task. 

Exits : 

Normal -- Return to the calling routine. 

Error -- Termination via ABEND macro 

instruction. SYSER before ABEND if one 
of the data sets is not of VAM 
organization. 

Operation : DUPCLOSE saves the calling rou- 
tine's registers and establishes base regi- 
sters for its CSECT and PSECT. It then 
retrieves the address of the DCBs f uses 
them to establish base registers for opera- 
tions on the DCBs, and places them in the 
parameter list it will pass to Close 
Common . 

DUPOPEN next tests both DCBs to ensure 
that the data set organization for each is 
VAM. If either DCB fails this test, a 
minor SYSER is declared* the address of an 
error message is loaded, and ABEND is 
called. If both DCBs pass the test, the 
RESTBLs for both data sets are found and 
base registers are set up. The addresses 
of both JFCBs are saved for later reference 
and Close Common is called with the address 
of the parameter list in register 1. 

The close operation xs assumed to be 
successful so no error test is made on 
return. DUPCLOSE begins searching for the 
JFCB associated with the primary DCB. It 
begins its search at the last JFCB and 
works its way backward through the TDT. As 
each JFCB is checked f its DD name is com- 
pared with the DD name in the DCB until a 
match is found. If no match is found the 
procedure is repeated for the secondary 
JFCB. When the primary JFCB is found, a 
test is made to see if any other DCBs are 
opened for the data set. If none is, tne 
duplicate JFCB pointer and the duplicate 
copy indicator are cleared. Following this 
or if another DCB is open, the TDT is 
searched again looking for the secondary 
DCB. The search is conducted in the same 
manner, the same tests are performed, and 
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the same processing occurs as in the case 
of the primary JFCB. 

When both JFCBs have been processed as 
above* DUPCLGSE returns to the calling 

routine. 



If any discrepancies exist, final house- 
keeping is performed to adjust the recorded 
data set length to the physical data set 
length. 

Control is returned to the caller by the 
RETURN macro. 



VSAM Close Routine (CZCOQ) 

VSAM Close is called by CLOSEVAM (CZCOB) 
and Stow (CZCOK) to perform terminal pro- 
cessing which is unique to VSAM data sets. 
(See Chart MG.) 

Entry Point : CZCOQ1 -- Entry is by type-1 
iinKage- 

I nput : Register 1 contains the address of 

the DCB. 

Modules Called : 

FLUSHBUF CCZCOV1) — Output contents of 
buffer pages f if necessary. 

PUT CCZCOS2) -- Complete the processing of 
the preceding locate mode PUT, 

Exit s: Normal return to calling program. 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for VSAM Close PSECT and 
CSECT, DCB f DCB header and RESTBL. 

VSAM Close is called to do terminal pro- 
cessing of a data set with respect to a 
DCB- The last operation field of the DCB 
CDCBLOF) is tested to determine if work 
remains to be done due to an outstanding 
locate mode PUT, If the last operation was 
a locate mode PUT* the user was given a 
pointer to. the output buffer where tne next 
logical record is placed. It is assumed by 
the sequential access method that if a 
locate mode PUT is called, the user has 
actually placed a record in the space pre- 
sented. The outstanding PUT must be ter- 
minated to include the last logical record 
in the data set, A call to a secondary en- 
try point CCZCOS2) is done to accomplish 
that function. 

The Last Operation and Hold Last Buffer 
flags CDCBLOF and DCBHLB) are cleared. 

The last record of a data set: has logic- 
ally been included in the data set, that 
is, data set pointers updated. That record 
must now :ie physically included in the data 
set. If , -:he last record has not been writ- 
ten from virtual storage, a call to 
FLUSHBUF ICZCOV) is made. An exception to 
this is undefined format records. Since 
they occur in page increments, they are 
written out at PUT time, and VSAM Close 
need not call FLUSHBUF. 



VISAM Close R outine (CZCQA) 

VISAM Close is called by Close and Stow 
to terminate processing of a data set 
(member) and output any existing directory 
pages. CSee Chart MB.) 

Entry Point : CZCQA1 — Entry by type-1 
linkage (privileged to privileged). 

Input : Register 1 contains the address of 
the DCB to be closed. 

Modules Called t 

PUT CCZCPA2) — Complete previous PUT if 
still active. 

MOVEPAGE CCZCOC1) -- Output directory 
pageCsK 

Exits : Normal return is made to the caller 
via the RETURN macro. 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for VISAM Close CSECT and 
PSECT, DCB # DCB header, and RESTBL. 

if the last operation was a PUT, PUT is 
entered at the secondary entry point to 
complete any function left outstanding from 
the previous PUT. 

If index sequential directories exist, 
and if the ISD Integrity flag in the RESTBL 
is set, MOVEPAGE (CZCOC) is called to out- 
put them. 

Control is returned to the caller by the 
RETURN macro. 

VAM ABEND Interlock Release Routine CCZCQQ) 

VAM ABEND Interlock Release is used by 
VAM to release interlocks that have been 
set within a task in which ABEND has been 
invoked. CSee Chart MI.) 

Entry' Points : 

CZCQQ1 — To release only RESTBL interlocks 
that may be set. Via type-1 linkage- 

CZCQQ2 -- To release all interlocks that 
may be set. Via type-1 linkage. 

Input : Register 1 contains the address of 
a half word field containing the ID of the 
task involving ABEND. 
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Mod ules C alled: 

Search SDST (CZCCE) — To update or delete 

data set or member entries in the shared 

data set table (SDST) . 

Interlock (CZCOH) -- To set read or write 

interlock on a shared data set entry. 

Release Interlock (CZCOI) ~~ To release 

read or write interlock on a shared data 
set entry. 

Exits : 



Normal — The calling program receives con- 
trol by use of the RETURN macro, with 
the T option set and no special return 
code. 

Error -- Kay ABEND if unable to release the 
SDST interlocks. 

Operation : The normal release process con- 
sists of analyzing the DCBHEADER interlock 
summaries (Figure 24) one at a time, and 
releasing the appropriate interlocks by 
calling the existent Search SDST, Inter- 
lock, and Release Interlock routines. The 
DCBHEADER interlock summaries are updated 
to indicate such release. 



Examining DCBhEADERs 
Release examines the 
neader to determine 
by the task that has 
finding a DCB header 
the interlock summar 
tinent interlocks ar 
below. If the compa 
ID in the DCB header 
ABEND is unequal, a 
next DCBriEADER withi 
comparison on task I 



VAM ABEND Interlock 
task ID in each DCB 
if the data set is used 
invoked ABEND. On 
pertinent to the task, 
y is checked and per- 
e released as stated 
rison between the task 

and that invoking 
link is made to the 
n the chain, and the 
D repeated. When the 



chain of DCB headers is exhausted (that is, 
the pointer to the next DCB header is 
zero), the link to the next JFCB is made 
and the process repeated until all JFCBs 
have been examined (that is, the pointer to 
the next JFCB is zero). 



Releas ing the Inte uoc_k s : The interlock 
summary in the DCB header is continuously 
updated as interlocks are set and reset by 
Interlock and Release Interlock, with the 
exception of the shared page table number 
interlock. The DCB header will reflect the 
condition of this interlock and it will be 
released as required. The DHDINT field in 
the DCB header contains the interlock sum- 
mary shown in Figure 24. 

If an interlock is recorded in the DCB 
header interlock summary as being imposed 
on the SDST control, all other interlocks 
within the SDST are released before releas- 
ing the SDST control interlock. If no 
interlock on SDST control byte is recorded 
in the interlock summary, and if such a 
lock is found to be in effect, either the 
interlock was set by the task which invoked 
ABEND and is recorded in a DCB header 
interlock summary that has not yet been 
examined, or the interlock was set by 
another task. Since it is not known at a 
givc^n moment which case exists, the first 
case is assumed, and the DCB headers are 
scanned for that particular lock. On 
release of the SDST control lock all other 
interlocks are released. While the scan is 
being executed, the SDST control byte is 
repeatedly checked for release. If release 
occurs (the second case is indicated) the 
scan is discontinued and the general 
, release process is executed. 
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Figure 24. DCBHEADER Interlock Summary 
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SECTION r >: VIRTUAL SEQU ENTIAL AC CESS MET HOD (VSA M) 



Snjuentia] organization is a subf unction 
of the VAM user macro instructions. The 

principal advantage ot VSAM is that the 

maximum record size is one segment (256 
pages or 1,048,576 bytes). 

The following contribute to VSAM; 

User Coded Macro Instructions 



DCB 



Supply parameters to define 
data set structure. Also 
provide work space lor the 
access method modules. 



begin and end on paqe boundaries. To con- 
trol the piece ;sinq ot tornut-V leootds, a 
length ront iol t \ela is placed in t he i usf 
tom bytes- of the r e-eoi d by the usei . The 
access method qene rates the riMitiol data in 
the first byte and also place a copy of the 
control field at the end ot the record. 
The pair of control fields (8 bytes) will 
never span a page boundary. 

A description of DCB working storage 
used by VSAM routines is provided in Table 
37. 



OPEN, CLOSE 



Activate/deactivate access 
to a data set. 



ROUTINES IN VSAM 



GET 
PUT 

3ETL 

PUTX 

C ontrol Blocks 
RESTBL 

^JSAM R outines 

OPENSEQ 



CLOSES EQ 



GET 



PUT 



SET] 



PUT> 



FLUSHB'JF 



Request a record. 

Specify generation of a 

record. 

Specify access to a parti- 
cular record or portion of 

the data set. 

Update a record in place. 



Relative external storage 
correspondence table. 



Access dependent initiali- 
zation to begin processing 
of a VSAM data set. 

Terminate sequential 
processing. 

Sequential access to a 
record of a VSAM data set. 

Sequential generation of a 
record and truncation of a 
data set. 

Specify the record within 
the data set at which 
access is required. 

Update a record without 
deletion of subsequent 
records as with PUT. 

Process the page buffer 

contents. 



VSAM Get Routine (CZCQR) 

VSAM Get is called, by expansion of the 
GET macro instruction, to obtain a data 
record from a VSAM data set or member. The 
record obtained may be explicitly identi- 
fied by a SETL or may simply be the record 
which sequentially follows that record 
accessed by the preceding PUTX or GET. 
(See Chart NA- > 



Table 37. Description of DCB Working 

Storage Used by VSAM Routines 



Record formats witl the VSAM may be 
fixed (F), variable P') , or undefined CU) 
(see Figure 25). These records may span 
page boundaries, but ormat-U records must 
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The USER 
specifies . 



VSAM organizes 

data set records like this . . 



RECFM --■ F 
LRECL 



*r 



- Page - 



- Record 1 - 



-Page- 



— Page- 



. — _ Page 



- Record 2- *4*" Record 3— »-r* Record 4- 

ln this example, LRECL = less than 4096. 



RECFM --" U 

LRECL 



«, ; Page »4« ■ Page • — — *4-* ■ — ■ — - Page M«* ■ — Page »-j 


J 1 I IS 

1 ! i i \ 

1 I I / 

i j i i ( 

,... ,, | I -,,,, , _.— _ 1 • „ „.. , in,,,.,, , r- --* 


.* _ Record 1 ■■ — — — — ~*-t"< ; Record 2 ■ — -H 



n rhls example, LRECL : 8 r 192 




and supplies a 4-byte field 
preceding eoch record in which 
he places the record length . 



The user supplies leading 
record length descriptor. 



Reserved for other use. 



Alignment: the number of bytes left 
at the end of a page (1 to 7) if it is 
necessary to skip to next page (if both 
£3 and tA would not fit on same page 
following record 3). 

This flag bit is set to 1 If record 3 is complete on a single page. 



Figure 25. VSAM Data Record and Page Formats 
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^^±41hi^ ? ^ : Read-only, reentrant, public, 
nonprivfieged, system. 



being processed. If it does not ABEND is 
called. 



E;rcry Point: CZCOR1 -- (iet is called by 
type-1 linkage. 

In put : Parameters are passed in general 

registers as follows: 

Register — - If move mode, address cf the 
users area. 

Register 1 -- Address of the DCB. 

Within the DCB, the macro code field 
(DCBMCD) has been set to indicate move or 
locate mode. 

Modules Calle d; 

MOVEPAGE (CZCOC1) — Perform page input* 

FLUSHBUF CCZCOV1) — Purge buffer of data 
remaining in the buffer since the last 
operation . 

Exits; 



Normal — Exit is made to the user via the 
RETURN macro. 

Error -- ABEND is called under the follow- 
ing conditions: 

• The DCB header does not point back to 

the DCB. 

• Record length zero. 

• Record length longer than maximum, 

• End of data set and missing EODAD. 

• Format U record not multiple of a page 
in length. 

• User area not same protection class as 
the DCB. 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for VSAM Get CSECT, DCB, SAVE 

area, DCB header, RESTBL, and ISA. 

VSAM Get Is a "fence sitter* and has no 
PSECT. It is always called by type~l link- 
age and assumes the same privilege as the 
caller. The VSAM Get save area is obtained 
dynamically by Open Common on a DCB basis. 
Get has to access the interruption storage 
area (ISA) to determine its current privi- 
lege state before calling privileged rou- 
tines (MOVEPAGE, ABEND and FLUSHBUF). Get 
will execute type-1 or type- 2 CALLs depend- 
ing on its privilege state. 

Tne DCB pointer in the DCB header is 
tested to insure that it points to the DCB 



The last operation field (DCBLOF) is 
tested to see If the last operation was a 
PUT. If tne last operation was a PUT, it 
means that the data set is positioned at 
end of data and the current Get would cause 
an End of Data condition. The End of Data 
exit in the DCB is taken if the user supp- 
lied one; if not ABEND is called. 



If the last operation was a Get, a call 
is made to FLUSHBUF CC2C0V) to clear the 
I/O buffer before reading in the next 
record. 

The following is common to all other 
previous operation conditions (SETL, PUTX, 
Get-move mode Get- locate mode where not 
more than one buffer page was retained) and 
to the preceding: if the current record 
position (page and byte) is beyond the end 
of data defined in the RESTBL (or member) 
header, call the user's EODAD routine as 
described above for PUT. 

The retrieval address of the current 
record and its successor are generated. 
Following this one of three procedures is 
executed depending on the record format. 



Undefined Record Format CU) ; ABEND will be 
executed if the requested record is too 
large, or if it would not end on a page 
boundary. The user's EODAD routine will be 
executed if the end of the record is beyond 
the end of the data set. In this case 
ABEND may be executed if no EODAD was 
specified. 

The number of pages to input is com- 
puted. If in move mode and the users area 
begins on a page boundary, MOVEPAGE 
(CZC0C1) is called to input the record 
directly into the user area. The last 
operation is set to GET- move mode. The 
current relative position is updated and a 
return is made to the caller. 

If in locate mode, or move mode where 
the user area does not begin on a page 
boundary, MOVEPAGE CCZCOC1) is called to 

read the record into the buffer assigned to 
the DCB. The number of pages in use is set 
equal to the number of pages input, and the 
Hold Last Buffer flag is set off* If in 
locate mode, the buffer address is placed 
in general register l f the Last Operation 
flag is set to GET-locate mode, and a 
RETURN is made to the caller* If in move 
mode, the contents of the buffer are moved 
to the user specified area and the Last 
Operation flag is set. to GET-move mode and 
a return is made to the caller. 
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Fixed Format (F) : A computation is made to 
determine if the next record is completely 
within the buffer- If (CZCOC1) is called 
to input enough pages to complete the reco- 
rd, starting at the page following the last 
page in use. The remainder of processing 
of fixed format records is common to both 
fixed and variable and is described below, 
under "Fixed or Variable Format (Common 
Processing) . " 



Variable Format (V) : 



If the buffer is 



empty, MOVEPAGE CCZCOCl) is called to read 
the next page of the data set into the 
buffer. The number of buffer pages in use 
is set to one. 



The record length of t 
buffer is checked to dete 
sent contents of the buff 
record. If not r MOVEPAGE 
called to read the additi 
the buffer at a point fol 
page in use. The number 
incremented by the number 
The retrieval address of 
is generated. 



he record in the 
rmine if the pre- 
er contain the 

(CZCOC1) is 
onal pages into 
lowing the last 
of buffer pages is 

of pages read, 
the current record 



Fixed or Variable Format (Common Proces- 
sing) : The record address of the following 
address is generated. The Hold Last Buffer 
flag is set on or off depending on whether 
the current record ends on a page boundary. 

If locate mode was requested, the 
address of tne record is placed into gener- 
al register 1 and a return is made to the 
caller. If in move mode, the current reco- 
rd is moved to the user area. If more than 
one page is in use in the buffer, or if the 
Hold Last Buffer flag is off, FLUSHBUF 
(CZCOV1) is called to purge the buffer area 
of the unneeded data. 

The Last Operation flag is set to GET- 
move mode, the current record position is 
updated and a return is made to the caller. 



CZCOS2 — Entered vie type-1 linkage to 
terminate an outstanding iocate-mode 

PUT. 

CZCOS3 -- Entered via type-2 linkage to 
permit privileged table storage. PUT 
enters itself to "jump the fence", 
become privileged, and update the 
RESTBL. 

Input : 

For CZC0S1, register contains the user 

buffer area (move-mode request) . 

Register 1 contains the address of the 

DCB. 

For CZCOS2, register 1 contains the address 
of the DCB. 

For CZCOS3 — None. 



Modules Called: 



Calls as follows: 
Output a diagnostic mes- 



VDMEP (CZCQK1) 

sage and terminate the function without 
terminating the task. 

FLUSHBUF (CZCOV1) — Purqe data remaining 
from a previous operation, from the 
buffer. 



E xits : 
Normal 



Return to the calling routine. 



Error — VDMEP is called under the follow- 
ing conditions: 

® User has READONLY access to data set. 

• DCB specified by caller is not 
addressed by DCB header. 

• Record length greater than maximum 
specified in DCB header (note that 
this error will not be detected until 
the following operation is performed 
when it is caused by a locate mode 
PUT). 



VSAM PUT Routine (CZCOS) 

VSAM PUT is called by the user through 
the DCB or by CLOSESEQ (CZCOQ) , or SETL 
(CZCOT) to concatenate a record onto the 
data set and define a new end of data set. 
When called by the user, the function may 
oe to obtain the address of some buffer 
space into which the user may construct a 
record. Any subsequent operation on that 
data set will result in a call to the 
secondary entry of this module (CZCOS2) to 
complete the operation. (See Chart NB.) 

Attributes ; Read-only, reentrant, public, 
nonprivileged, system. 

Entry Points : 

CZCOS1 — Entered via type-1 linkage. 
Normal entry point. 



• Undefined (U) format record whose 
length is not in page multiples. 

• Variable format logical record length 
is too small (less than 4 bytes). 

Operation : This module's operation can be 
summarized as entry; initialization; com- 
pleting processing of the previous opera- 
tion; establishing the buffer position for 
the current operation; if move mode, 
transferring the data from the user's area 
to the buffer area; and writing the data on 
external storage if more than one buffer 
page is left in use. 

At entry CZCOS1 , the entry indicator (Q) 
is set to zero; at entry CZCOS2, Q is set 

to one. Initialization and general regist- 
er storage is executed in conformance with 
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imkckqe conventions- ti*ir,e registers are 
declared for the CSECT, DCB, save area, DCB 
header, RESTBL and ISA. 

VSAM PUT is a "fence sitter", and has no 

PSECT. It is always called by type-1 link- 
age and assumes the same privilege as the 

caller. The VSAM Put save area is obtained 
dynamically by Open Conmon on a DCB basis. 

VSAM PUT has to access the interruption 
storage area USA) to determine its current 
privilege state before calling privileged 
routines. It will execute type-1 or type~2 
CALLS depending on its privilege state. 

Last Operation Not PUT : Data may still 
exist in the buffer and must be released. 
If the last operation was a locate mode 
GET, and more than one page is in use, 
FLUSKBUF CCZCOV1) is called to release the 
pages* If the last operation was not a 
locate mode GET, FLUSHBUF is called if the 
present position is not at end of data set, 
and this is not the first PUT, Processing 
continues at the point, below, "Last Opera- 
tion PUT Locate Mode." 

Last Operation PUT Locate Mode : The record 
length is obtained from the DCB or from the 
buffer if the buffer is format-V. If the 
record length is greater than the maximum, 
VDMEP is called. 



The number of pages which the record 
occupies is stored as the number of pages 
to output and also as the number of buffer 
pages in use. If the Hold Last Buffer flag 
is off or, if on and more than 1 page is to 
be output, FLUSHBUF (CZCOV1) is called to 
empty the buffer. The end of data set 
parameter In the RESTBL is incremented by 
the number of bytes in the record just 
processed. 

If the record is format-U the operation 
is move, and SWITCH is off, the end of data 
set value is moved from the RESTBL to the 
DCB. If either the Q or X (move mode) 
flags are on, the last operation is set to 
PUT-move mode, and return is made to the 
caller. This completes processing for the 
preceding locate mode PUT operation and 
also certain move mode PUT operations. The 
processing of the current call is described 
below. 



Processing Current Record ; If locate mode, 
the last operation is set to PUT-locate 
mode, the current buffer position is placed 
into general agister 1 and, if format-V # 
the record length of the previous record is 
placed in the buffer and general register 1 
is incremented by U. Then a return is made 
to the caller. 



Common Processing to Update Buffer Posi- 
tion : If not format-V, the buffer position 
is incremented by the record length from 
the DCB. 

If format-V, the current buffer position 

is updated by the length- indication field 
in the record, A flag is set in the record 
length control field to indicate that the 
record is or is not complete within one 
page. If the number of bytes on this page 
and following the record is between zero 
and 7, the control field will be placed on 
the next page with a gap of between zero 
and 7 bytes. This gap, the alignment 
bytes, is accounted for in the record 
length control fields at the beginning of 
the record, and In the field between this 
record and the following record. The con- 
trol field is then placed following the 
record and the buffer position is updated 
by 4. 

For either of the above, the Hold Last 

Buffer flag is set on. 

Common Processing to Output Data : The 
number of buffer pages in use is computed, 
eased on the size of tne current record 
plus the number of bytes in the buffer pre- 
ceding this record including those in the 
first page on which it is stored. If the 
low 12 bits of this number are zeros and 
this is not a format-V record, the Hold 
Last Buffer flag off is turned off. 



If move mode, the X switch is set on. 
If the record length exceeds the maximum, 
VDMEP is called. 

If records are not format-U or are 
format-U but the user's area does not begin 
on a page boundary, the record is moved to 
the buffer and complete processing with the 
same procedure described above at "Common 
Processing to Update Buffer Position* 
occurs. This also sets the SWITCH field to 
on for format-U records. 

If format-U and the user area is on a 
page boundary, the Hold Last Buffer flag is 
turned off, the current buffer position is 
updated, FLUSHBUF is called to release tne 
pages, and processing is concluded as 
described above, at "Common Processing to 
Output Data." 



SETL Routine (CZCOT) 



SETL is called by VSAM Open CCZCOP) , 
Find CCZCOJ), and by the SETL maci o using 
the V-con and R-cons stored in the DCB to 

specify access to a particular record 

within the VSAM data set. (See Chart NC.) 

Attributes : Read-only, reentrant, public, 
nonprivileged, system. 



Restrictions : 



Cannot use SETL B with unde- 



fined CU) format records. 
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Entry Point: CZCOT1 -- This modal o is 
called by type-1 linkage. 

Input : The following parameters are 
passed: 

Register -- The retrieval address field. 

Register 1 — Address of the ECB. 

Retrieval address is specified only when 
the type code is R. In addition, a type 
code is preset in the macro field (DCBMCD) 
to indicate: 

B - Beginning of data set. 

E - End of data set. 

P - Previous record. 

R - Retrieval address. 

Modules Called : 

MOVEPAGE (CZCOC1) — Input a page into the 
buffer associated with the DCB. 

VSAM Put CCZC0S2) — Complete preceding 
locate mode PUT. 

FLUSHBUF (CZCOV1) -- Purge buffer of 

unstored data from preceding operation. 

Exits: 



Normal — Return to the calling routine. 

Error — ABEND is called under the follow- 
ing conditions: 

• DCB header does not point to DCB. 

• Invalid record format in DCB. 

• Backspace request for undefined 
record. 

• Attempt to SETL outside limits of data 
set, with no EODAD exit supplied. 

• Request code not defined (not a SETL 
type code) . 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage standards. Base registers are 
declared for the CSECT, save area, DCB f DCB 
header, RESTBL and ISA. 

SETL is a "fence sitter" and has no 
PSECT. It is always called by type-1 link- 
age and assumes the same privilege as the 
caller. The SETL save area is obtained 
dynamically by Open Common on a DCB basis. 
SETL has to access the interruption storage 
area (ISA) to determine its current privi- 
lege state before calling privileged rou- 
tines. SETL will execute type-1 or type- 2 
CALLs depending on its privilege state. If 



the address of the DCB in the DCB header is 
not equal to the DCB address passed in the 
parameter list, or the record format field 
in the DCB is unspecified, ABEND is used to 
terminate the task. 

If the preceding operation vas a locate 
mode PUT, it will be completed by calling 
VSAM PUT at entry point CZC0S2. 

If the last operation was a locate mode 
GET and if the Hold Last Buffer flag is on, 
or more than one buffer page is in use, 
FLUSHBUF (CZCOV1) is called to release the 
buffer and, if necessary, return data to 
external storage. Upon return from 
FLUSHBUF, the current record position will 
be updated. 

The last operation field is set to indi- 
cate SETL and a series of tests is then 
made to select the proper method of 
generating a retrieval address in the DCB 
(DCBLPA) . 

* Backspace (P) : If this is a forroat-U 
data set, the task is terminated via 
ABEND. For variable format records, if 
the current position is at a page boun- 
dary, and this is not the first page of 
the data set, MOVEPAGE is called 

CCZCOC1) to read the next page* Then 
the length control field is obtained 
for the preceding record and adjust it 
by the alignment byte count. For fixed 
format, the record length is subtracted 
from the current retrieval address 
Cthis is done separately on page number 
and byte position) . A negative result 
causes an exit to the EODAD routine, if 
one is supplied; otherwise the task is 
abnormally ended. 

* Beginning (B) : The retrieval address 
is set to zero. 

* Retrieval address (R) : If the retriev- 
al address specified by the caller is 
beyond the end of the data set, exit is 
made to the EODAD routine if one is 
supplied. If there is no EODAD routine 
an ABEND is issued. If the address is 
within limits that value is saved in 
the DCB. 

* End of Data Set CE) : The end-of-data- 
set field in the RESTBL (or member) 
header is moved into the retrieval 
address field in the DCB. 

After the retrieval address has been 
generated as indicated above, if any buffer 
pages are in use and the page number of the 
current page is not equal to that of the 
retrieval address, the Hold Last Buffer 
flag is reset and FLUSHBUF (CZC0V1) is 
called to remove that data from the buffer. 
If the retrieval address is not beyond the 
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end of the data set, MOVEPAGE (CZCOC1) is 
called to read the first page of the speci- 
fied record into the first page of the 
buffer. The number of buffer pages in use 

is set to 1. 

The fields in the DCB which define the 
current record are then set up and a return 

is made to the caller. 

PUTX Routine CCZCOU) 

PUTX Rewrite a Logical Record is called 
by a PUTX macro instruction in the user' s 
program to perform the rewriting of a log- 
ical record in a VSAJM data set. Initially 
PUTX checks the validity of the request, 
and if satisf actory, the buffer page (or 
pages) containing the record is (are) 
returned to the data set by linking to the 
FLUSHBUF CCZCOV) routine. (See Chart ND«) 

Attributes : Read-only , reentrant, non- 
privileged, public , system. 

Restrictions : The previous I/O macro 
instruction for this data set roust be a 
locate mode GET. After manipulating the 
data, the user may not change the size of 
the logical record when it is inserted in 
the buffer. 



I'UTX is a "fence sitter" and has no 
PSECT. It is always called by type- t link- 
age and assumes the same privilege a> the 
caller. The PUTX save area is obtained 

dynamically by Open Common on a DCB basis. 
PUTX accesses the interruption storage area 
(ISA) to determine its current privilege 
state before calling a privileged routine. 
PUTX will execute type-1 or type- 2 CALLs 
depending on its privilege state. 

PUTX verifies that the DCB header in the 

RESTBL points to the same DCB indicated in 
general register 1, and that the last I/O 

operation stored in the DCB was a locate 
mode GET. 

If either of the above are not satis- 
fied, an exit to ABEND occurs, 

VDMEP is called to terminate the func- 
tion and issue a message if the read-only 
access flag is on in the DCB header. 

Processing continues by setting, in the 
DCB, the number of output pages to be 
rewritten equal to the number of buffer 
pages in use; the number of the first out- 
put page equal to the first buffer page; 
the indication in the Last Operation flag 
(DCBLOF) to PUTX. 



Entry Point : CZCOU1 -- Entered via type-1 

linkage. 

Input : Register 1 contains the address of 

the DCB. 

Modules Called : 

FLUSHBUF (CZC0V1) — Writes buffer page (or 
pages) to data set. 

'VDMEP (CZCQK1) -- Terminates the function 
and outputs message if user has read- 
only access. 

Exits: 



Normal -- Return to the calling routine. 

Error — ABEND is called under the follow- 
i ng condi t ions : 

• The DCB header in the RESTBL does not 
point to the DCB indicated in the PUTX 

macro instruction. 

• The previous I/O operation for this 
data set was not a locate-mode GET. 

VDMEP is called if the read-only access 
flag is on in the DCB header. flag is 

on in the DCB header. 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage convention. Base registers 
are declared for the CSECT, SAVE area, DCB, 
DCB header, and ISA. 



If there is more than one buffer page to 
be rewritten, or if a hold does not exist 
on a single buffer page, FLUSHBUF is called 
to write out the necessary pages. On 
return from FLUSHBUF, processing is con- 
cluded by updating the current position 
pointers. If one buffer page is to be 
rewritten, and a hold exists for this page, 
FLUSHBUF is bypassed. 

Processing concludes by updating the 
current relative position pointers to 
reflect the record just processed. This 
includes the page number pointer, the byte 
position pointer, and the buffer position 
pointer. PUTX then issues a normal return. 

FLUSHBUF Routine (CZCOV) 

FLUSHBUF is called by VSAM Get (CZCOR), 
VSAM Put (CZCOS) , SETL (CZCOT) , or PUTX 
(CZCOU) to return data in the buffer to 
external storage. (See Chart NE. ) 

Attributes ; Read-only, reentrant, public, 
privileged. 



Entry Point ; CZCOV1 
or type-2 linkage. 



Entered via type-1 



Input : Register 1 contains the address of 
the DCB. 

Modules Called : 

MOVEPAGE (CZCOC1) — Force buffer contents 
to be written on external storage. 
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Insert/ Delete Page CC2COD1) -- Assign 
external storage to data pages in the 
buffer. 

VDMEP CCZCQK1) — Output a diagnostic mes- 
sage and terminate the function (without 
terminating the task) • 

Exits : 

Normal — ■ Return to the calling routine. 

Error -- VDMEP is called under the follow- 
ing conditions: 

• Invalid return code from Insert/Delete 
Page (CZCOD1) . 

• No external storage space available. 

• Storage ration exceeded. 

• No secondary storage space specified, 

• Attempt to expand RESTBL for shared 
data set. 

• Maximum data set or member size 
exceeded. 

• Insertion beyond end of data set. 

• Deletion beyond end of data set. 

Operation : FLUSHBUF stores general regis- 
ters in conformance with linkage conven- 
tions and establishes base registers for 
the DCB, DCB header, and RESTBL or member 
header . 

If the number of pages to output is non- 
zero, and greater than the number checked 
out, Insert/Delete Page CCZC0D1) is called 
to assign enough pages to complete the 
request. The insertion is made at the page 
following "the last page checked out. The 
number of pages checked out is increased by 
the number inserted. Subsequent processing 



depends on tests made of the Hold Last 
Buffer flag (HLB), number of pages to out- 
put (NPO) , and buffer paqes in use (BPU) , 
and affects the number of pages checked out 
as illustrated in Table 38. 



After the 
1 # 2, and 3, 
no pages are 
tion is set 
the buffer, 
use is reset 
to the ca lie 
and the Hold 
buffer pages 



operation indicated for cases 
in Table 38 are performed, if 
checked out, the current posi- 
to indicate the beginning of 
the number of buffer pages in 
to zero, and an exit is made 
r. If pages are checked out 
Last Buffer flag is off, all 
checked out will be released. 



The number of pages is reduced by the 
number of pages that has been checked out. 
At this time if a page is still checked 
out , it is moved to the beginning of the 
buffer area and addresses and counters in 
the DCB are adjusted to indicate that the 
current record is in the first buffer page 
and that one page is in use. This routine 
then returns to the caller. 



Table 38. FLUSHBUF Decisions to Control 

Buffer Allocations 



J HLB 
| Flag 



j C 2) ON 



I 



\ I 

NPOf bPUf 



Action 



| Resulting \ 

\— T — T— \ 

| NPOJBPUj PCOi 



| | Call MOVEPAGE (CZCOC1) t 
| | output all pages in the 
| | request 

t I 

I 1 t 
I I 

1 j 1 |Same as (1) 



t 



I Call MOVEPAGE CCZCOC1) to f 
I out put all pages except thef 

j last, Move last buffer j 

| page to toe first buffer J 
{pacje and RETURN. | 



\ ♦Teiminat inq action described in text. 
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SECTION 6: VIRTUAL INDEXED SEQUENTIAL ACCESS METHOD (VISA M) 



vi : ;am o verv iew 

VISAM is designed to give the user 
sequential or nonsequential access to a 
record within the data (member) by search- 
ing for the user specified key* The key is 
a field located at a uniform position 
within each record of a data set. The fol- 
lowing contribute to VISAM: 

User Coded Macros 



Table 39 . Description of DCB Working 

Storage Used by VISAM Routines 



DCB Supply parameter to define data 
set structure. 

READ Request access or .specify 

WRITE creation of records within VISAM 

data set. Also generates a DECB 

(parameter list) . 

S£Th Request location of a specified 

record. 

LSETL Specify release of a record that 
was located. 

RELEX Specify release exclusive control 
of a page* 

DELREC Specify deletion of a VISAM data 
record. 

GET Request a record. 

PUT Specify generation of a record. 

Note: Records must be generated 
in sequence when using this 
macro. 

Control Blocks 

DCB Data control block — Extended 

index sequential working storage. 

DECB Data event control block used to 
control a READ or WRITE 
operation. 

KESTBI. Relative external storage corres- 
pondence table. 

POD Partitioned organization directo- 
ry (if partitioned) . 

Tables 39 and <*0 show fields of the DCB 
and DECB control blocks used by VISAM 

routines . 

General VISAM Routines 



r _„_. — T _. T . 

1 Symbol | Data !' 



Description 



DCBPCC , 


N t 


DCBOPC 


N | 


DCBCL ! 


A | 


DCBCCL 


X r A | 


DCBI0S | 


X | 


DCBPT 


x I 


DCBCRL 


N | 


DCBCRS 


X | 


DCBRES 


X | 


DCBPLM 


X i 


DCBPMM 


X | 


DCBOLM 


x I 


DCBASY 


X | 


DCBRK 


A | 



Overflow page counter 



Current VISAM locator 
position relative to page 



Contents of current locator 

X'OOOCT through X f OFFF f = 
on- page 

X f 1000 s through X'FFFF S = 
off-page 

Input, Output switch 

Page type 

X M FF 9 overflow page 
X , 00 t data page 

Current record length 

Current record switch 

Read exclusive switch 

PUT locate mode only 

£UT move inode only 

Outstanding locate mode GET 

Asynchronous switch 

Record key area for previous 
record 



VISAM 
Put 



Sequentially generate or truncate 
records of a VISAM data set. 



SETL 



ESETL 
RELEX 

READ 
WRITE 



Search VISAM data set for a reco- 
rd. Set current key location of 
a VISAM data set record. 



Release a page. 



Nonsequential generation or 
retrieval of a VISAM data set. 



VISAM 
Get 



Sequentially obtain records of a 
VISAM data set. 



DELREC 



Remove a record from a VISAM data 

set. 
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Add Directory 

Entry Add directory € v ntry. Update 
VISAM kc^y directory. 



Table *40. 



«,ETPAGE 



VISAM 
Open 
VISAM 
Close 



Interfaces with VAM General Ser- 
vices to control page I/O. 



op« i n and close data 
dependent) . 



>t (access 



VISAM Page Formats 

The following types of page constitute a 
VISAM data set (member). (Also see Table 
41.) 

Data and overflow pages consist of data 
records and locators. The data records are 
placed on a page starting at the top (low- 
est numbered bytes) and are added towards 
the bottom (increasing byte locations). 
Locators, on the other hand, begin at the 
end of the page and extend toward beginning 
(highest numbered bytes to lowest). 

The locators are a series of 2- byte 
fields which, when examined in sequence, 
give the location of records in ascending 
sequence by key, regardless of arrangement 
of records on that page or any number of 
overflow pages. There are 2 types of 
locators : 



| .Symbol | Data { 

t + + 

|D ECF.cn s x 1 


i DEC ECO 




IDECTYP 


X j 


| DECTYi 


* i 


j DEC«40 




i DEC 4 3 




J DEC UU 




\ DECU8 




| DEC U 9 




| DEC* A 




| DECTY 2 


X J 


| DECT9M 




IDECLEN 


N I 


IDECDCB 


A j 


| QECKAD 


A | 



Fields and Codes of the DECB 
Referenced by VISAM Routines 
(CHADEB) 

Description 

operation completion code. 
X'OO* H«Md/Writfr code. 
Operation Type Code. 

First byte of operation field defined as 

Operation 



1 



Code 

Internal External 
X'UO' KR 



Write replace by re- 
trieval address. 

X'U3 f KS Write replace by key. 

x*HW KT Write new key. 

X'HB* KY Read by key. 

X'UV KZ Read by retrieval 
address. 

X'ttA* KX Exclusive read by key. 

Second byte of operation field is defined 
as operation modifier. 

x'MO' Character m s 9 appeared in the area 
field of the macro instruction. 

Data area length. 

Location of DCB. 

Location of the key or retrieval address. 



• Onpage locators whose values range from 
X^OOA* to X'OFFo* and specify the 
starting byte of the corresponding 
record. The values X f 000* through 
X f 009' and X , 0FF9' through X'0FFF f are 
unattainable. 

• Offpage locators whose values range 
from X'lOOO' to X'FFFF'. The first 
byte of an offpage locator specifies 
the page number of the overflow page 
incremented by 16 f on which the data 
record may be found. The second byte 
specifies the relative position of a 
locator on the overflow page which will 
in turn specify the starting byte loca- 
tion of the proper record . 



Table 41. Organization of a VISAM Data Set 



Title 

Directory 
(D) 



overflow 
CO) 



Optional 
Yes 



Max. \ 

Pages | Description 

255 (Consists of the lowest key 
Jfroic each data page after the 
\ first. Appears in data sets 
| < members) consisting of more 
| than 1 data page. 

I 
2U0jContains data records and 
(locators when there is not 
[sufficient space on the data 
| page with which its key is 
| associated. 

I 
65, OOOf Contains data records and 
I sequentially organized 
(locators. 



Keys on directory pages winch are write- 
protected from the user, are automatically 
placed there as each, except the first, 
data page is generated. 

The lowest key associated with a data 
page is the one which appears in the direc- 
tory position corresponding to that page. 
If a record is added to a page, and this 
record has a lower key than any other key 
associated with that data page, the direc- 
tory is updated to reflect the new value. 
An inserted record on a page may cause 
Jocators to be displaced to subsequent 
pages -- this case also causes the directo- 
ry to be updated. 



In order to reduce paging on VISAM data 
sets with large directories, a super inde- 
xed sequential directory (SISD) is created 
when the number of directory pages exceeds 
2 and a SETL by KEY is performed. The key 
fields in the SISD consist of the first 
whole key on a directory page, and the 
address of that key relative to the begin- 
ning of the directory page on which it 
resides (byte = directory page number; 
byte 1 = key offset within page) . The for- 
mat for the SISD is shown in Table 4 2. 
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Table U2. VI SAM Page Formats — Super 
Indexed Sequential Directory 



Table 43. 



VISAM Paqe Formats 
Overflow 



Dat a or 



| Bytes | Symbol | Contents 

1 0-1 jPAGNUM (No. SISD pages. 

I 






I 2-3 



J 4-5 



;6™7 



|8-9 



I 



110-4095 



VMSPACEJNo. VM pages occupied by 

(the directory. 

I 
ENDSISDjEnd of SISD directory 

(relative to the beginning 

| of the last SISD 

(directory page. 

I 
ENDDIR {End of ISD directory 

| relative to beginning of 
| last ISD directory page. 

I 

|X f 0000 s 

I 

{Keys and ISD relative 

| addresses. Note that 
|keys and Its address may 
Jspan paqes- 

._. .x . . . . 



|When space is allocated for the SISD and 
j until it is updated, bytes 4-7 will 

| contain X f FFFFFFFF f . 

i . .. ____ — . „.. . . 



A READ or SETL by key will cause the 
following : 

• Search directory for the largest Key 
which is smaller than or equal to the 
one supplied by the user- 

• Access the indicated data page. 

• Using the locators on that page, search 
for the desired record. Note that this 
may cause overflow records to be read* 

The relationship between locators and 
records, data pages and overflow pages is 
depicted in Figure 26. This diagram illus- 
trates variable length records , overflow 
records 9 available space and recoverable 
space. To summarize, the sequence of reco- 
rds is determined not by their sequence on 
a page, but by the order of the locators 
which address the records. 

The formats of data and overflow pages 
are shown in Table 43. The format of di- 
rectory pages is shown in Table 44. 



VISAM ROUTINES 

The VISAM processing for VISAM Put, 
VISAM Get, S£TL f READ/WRITE DELREC, GET- 
PAGE, and Add Directory Entry is described 
below. 



r — .. . r — , T , 

| Bytes j Symbol | 



Contents 



| 0-1 

2-3 

[4-5 

[6-7 

|8-9 

[I0-ENDDAT 

(ENDDAT+1) | 
| to (EOS-1) | 

|EOS~4093 
14094-4095 



|PAGNUM|Page number (starts 
.from zero) 

lEN.DDATjEnd of data relative to 
| PTR to the beginning of 

| unused spaces 

jDATSPAfData space. Total 
| number of bytes 
j containing data records 

| ENDDIR (End of space accounting 
| area C bytes 0-9) in 
[this page value is 
)X t 0009 , ~ 

| RECSPA | Recoverable space. 

[Number of bytes deleted 
| from the data area 

| Data records and 
| recoverable space 

| Unused space 



| Locators (half word 
|each) 

| EOS | End of available space 
[relative to start of 
[page. Points to start 
I of locators 



Table 44. VISAM Page Formats ~ Directory 

r _ r T . _ 1 

| Bytes | Symbol | 
| + + _ 



Contents 



0-1 



2-3 



4-5 
6-7 

8-9 
10-4095 



PAGNUM 



DIRPG 



ENDDIR 



Total number of directory 
pages (starts from one) . 

Number of pages in 
directory , used for 
maintenance of the virtual 
memory length of the 
directory buffer after the 
directory is read into the 
buffer. 

X s 0000' 

End of directory relative 
to pointer to the 
beginning of last data 
page. 

X'OOOO' 

Keys. Note that keys may 
span pages. 
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Spoc e Ate Qunt ( ng 



* J 



~1 ' 



Overflow Poi 



SpGCe Ac CO jnttng 



43 43 



LL 



C 



f ? Ore length * *n* I dl 



X is recoverable ipoce 
A is ovailable spate 

K. iii-ey 

D *s dato 

EOS is end of space. 

Alt records of a data tet of member will be of o uniform 
format with regord to key length, iocotion of key, variable 
or fixed, if fined, oil will be of the wme length.' 



Figure 26. VISAM Record Relationship 



rzn 



•Nofe: 

There wi! 1 be c 
corresponding locator 
on the data page, 
as shown fee record 2. 



VISAM Put Routine (C2CPA) 

VISAM Put is called by the user (through 
the DCB) to concatenate a record in the 
user's area onto the data set, or to pro- 
vide the user with a buffer area into which 
to construct a record. This module may 
also be called by GET (CZCPB), GETPAGE 
(CZCPI), SETL CCZCPC), READ/WRITE/DELREC 
CCZCPE) , or VISAM Close (CZCQA) to complete 
processing of a preceding locate mode PUT. 
(See Chart OA. ) 



Attributes : Read-only, reenterable, privi- 
leged, public. 

Entry Points ; 

CZCPA1 — Normal entry from expansion of 

PUT macro instruction. Entered via 

type-1 linkage. 

CZCPA2 -- Entered to complete previous 
locate-mode PUT. 



Input : 

For CZCPA1, register contains the address 
of user area (move-mode only) . Register 
1 contains the address of the DCB. The 
macro code field of the DCB is set as 
follows; 



■0000' Locate mode. 

• 00 04' Move mode. 

'0008' Move mode complete. 

For CZCPA2 -- Register 1 contains the 
address of the DCB. 



Modules Called : 

GETPAGE (CZCPI) — Perform input and/or 
output of pages. 

Ada Directory Entry (CZCPL1) — Update tht 
index sequential directory. 
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VDMEP CCZCQK1) — Terminate the function if 

read-only access is indicated. 



have been opened toi the data set 
OUTPUT option. 



nth the* 



,LX1* 



Normal -- Control is passed back to the 

caller by use of the RETURN macro • Gen- 
eral register 1 will always contain the 
address of the record, 

r,rror — Depending on the error condition, 
an exit may be made via ABEND or VDMER 
or, where provided , to a user's SYNAD 

routine, 

ABEND occurs if: 

• The record length exceeds 4000 bytes, 

• The record length exceeds the maximum 
stated in the DCB Cwhen completing a 

previous PUT) . 

• A SYNAD condition is encountered dur- 
ing completion of a final PUT* 

VOMER occurs if: 

• The user has read-only access. 

• The DCB is not open for output* 

• Two or more DCBs are open with OUTPUT 
specified for a nonshared data set* 

• An unexpected return code is received 
from GETPAGE. 

Conditions for which the user may pro- 
vide a SYNAD routine and the codes which 
PUT will provide in DCBEX2 are: 

Keys equal C sequence error) X f 0*4 s 

Keys out of sequence '0C 

Record length exceeds that spec- •1C* 
ified in DCB 

Operation : VISAM Put is a * fence sitter,* 
and has no PSECT. It is always called by 
type-1 linkage* and assumes the same privi- 
lege as the caller . The Put save area is 
obtained dynamically by Open Common on a 
DCB basis. Put has to access the Interrup- 
tion storage area (ISA) to determine its 
current privilege state before calling pri- 
vileged routines. Put will execute type-1 
or type- 2 calls depending on its privilege 
state. 

PUT Normal En try : Initialization and gen- 
eral register storage is executed in con- 
formance with linkage conventions. Base 
registers are declared for the CSECT, DCB, 
DCB header, RESTBL and data page. Initial- 
ly, VDMEP is called via the VOMER macro 
instruction if the user has read-only 
access to the data set, if the data set is 
not open for output, or if two or more DCBs 



If the previous operation was a PUT, an 
internal subroutine, "Complete Previous 
PUT* is executed. Processing continues to 
find space for a new record. 

If any pages exist beyond this page, the 
number is computed and GKTPAGE CCZCPI3) is 
called to delete them. If this is not the 
first data page r Add Directory Entry 
CCZCPL1) is called to update the directory. 

If any records exist, on this page beyond 
the current position, they are deleted one 
by one until the locator indicated by the 
end-of -space field is reached* Each record 
deleted causes the data space to be 
increased by 2 bytes, and recoverable space 
to be incremented by the length of the 
record. 



Find Space for New Record ; The last opera- 
tion switch is set to PUT. If a page is 
assigned, and either more than **O0O bytes 

are available, or padding space, plus a 
locator, plus record length is not greater 
than data space, then a page is not 
required. If a page is not assigned or 
insufficient space exists, GETPAGE CCZCPI1) 
is called to insert a new page. The cur- 
rent locator address is set to 4092 , the 
new page switch is set on and the addresses 
of the current locator and buffer position 
are generated. 

If move mode, the record is moved from 
the user area to the data page after check- 
ing that the record length exceeds neither 
4000 (ABEND) , nor the value stated in the 
DCB as a maximum (SYNAD). 

The current buffer address is placed in 
register 1. If the operation being per- 
formed is not a PUT- move mode complete, 
control is returned to the caller- If the 
operation was PUT- move mode complete, the 
previous PUT is completed. Contxol then is 
returned to the caller . 

PUT Secondary Entry ; Base registers are 
established as above, SKIP is turned on and 

the internal subroutine "Complete Previous 
PUT" is executed, GETPAGE CCZCPI3) is 
called to output the data page, A RETURN 
is executed. 

Complete Previous PUT : The key in the cur- 
rent record is compared against the key of 
the previous record. If out of sequence or 
equal, SYNAD exits are executed. If this 
is a new page. Add Directory Entry (CZCPL1) 
is executed to update the directory. If 
format-V, ABEND is executed if user 
exceeded the record length limit in the 
DCB. 
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End data and data space are updated by 
tne length of th<- current record. End of 
space is updated and ^* new locator is 
inserted. The subroutine returns to the 
portion of this module that called it. 



VISAM Get Routine CCZCPB) 

VISAM Get is a routine CctLied by the 
user through the DCB to obtain access to 
the next logical record, (See Chart OB- > 

Attn butes : Read-only, reenterable, publ- 
ic, privileged. 

Entry Point : CZCPB1 -- Expansion of the 
GET macro generates linkage to this module. 

Input : Parameters are passed as follows: 

Register -- Address of user area. 

Register 1 -- Address of DCB. 

The macro code in the DCB CDCBMCD) is 
set to indicate move or locate mode* 

X'0000' = Locate mode. 

X'0004' = Move mode. 

Modules Called : 

PUT (CZCPA2) — Complete outstanding PUT 
operation. 

GETPAGE CCZCPI2) -- Input next page of the 
data set. 

Exits : 

Normal — General register 1 will contain 
the address cf the record. 



EODAD 



Position is at end of data set. 



Error -- ABEND EODAD is unresolved. 

Operatio n: Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for DCB, GET save area, CSECT, 
and ISA. Base registers for DCB header, 
data page, and RESTBL are declared as 
needed. 

VISAM Get is a "fence sitter," and has 
no PSECT. It is always called by type-1 
linkage and assumes the same privilege as 
the caller. The Get save area is obtained 
dynamically by Open Common on a DCB basis. 
GET has to access the interruption storage 
area (ISA) to determine its current privi- 
lege state before calling privileged rou- 
tines. GET will execute type-1 or type-2 
calls depending on its privileged state. 

The DCB (DCBPLM) is tested to determine 
if the last operation was a PUT. The 



secondary entry point or PUT (CZCPA2) is 
entered to terminate any outstanding PUT*.. 

Before getting the record, if the data 
set is not shared and the data page in the 
buffer is not the current data page, the 
buffer data page is output via GETPAGE 
prior to bringing the current page into the 
buffer. 

The Current Record switch in the DCB 
CDCBCRS) is tested to see if the DCB is 
currently positioned to the proper record. 
If the Current Record switch is on tf the 
current locator is obtained. The locator 
may be. a data page locator or point to an 
overflow page. If it is an overflow page 
pointer the overflow page is obtained by a 
call to GETPAGE (CZCPI). The next logical 
record is located on the data page or the 
overflow page. The record address, key 
address, and retrieval address are set from 
the found record. 

If a move mode GET was requested, the 
record is moved to the user supplied area. 
Control is then returned to the caller by 
the RETURN macro. 

If the Current Record switch was not on, 
the locator of the next logical record must 
be obtained. If the current locator is not 
at the end of the locators on the current 
page, the location of the locator is 
updated to the next logical record and pro- 
cessing continues as if the Current Record 
switch were on. 

If the current locator was the last one 
on that page, the page number is incre- 
mented and the next page obtained by cal- 
ling GETPAGE CCZCPI). If the call to GET- 
PAGE caused an end-of-file condition, the 
user-supplied Cin the DCB) EODAD exit is 
taken, if it exists. If the user did not 
provide an EODAD, VDMEP is called. For a 
non-end of data condition, the locator 
pointers are initialized and processing 
continues as if the Current Data switch 
were on. 

SETL Routine CCZCPC) 

SET LOCATION (SETL) is called by the 
user or by READ/WRITE to locate a specific 
record within a VISAM data set or member. 
(See Chart OC. ) 

Attributes ; Read-only, reenterable, publ- 
ic, privileged. 

Restrictions : May not SETL by retrieval 
address for a shared data set« 

Entry Points : 

CZCPC1 — Entered via type-1 linkage 

through expansion of the SETL macro 

instruction. 
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C7.CPC2 -- Entered via type-1 linkage from 
other VISAM routines. 



Input ; 

for CZCPC1 , reqint.er contains the address 
of key or retrieval address. Register 1 
contmnn the addresr; of the DCB. The 
macro code field of the DCB will be set 
to one of the following: 



'GO 
f 08 

• ia 

8 18 
*80 



SETL operation to beginning. 

By key. 

By retrieval address. 

To previous. 

To next. 
To end. 



For CZCPC2* register 1 contains the address 
o„ c a two-word parameter list: 



Word 1 



Address of DCB. 



Word 2 — Address of key or retrieval 
address. 

The macro code field of the DCB has the 
same permissible values as for entry point 
CZCPCi . 



Modules Called : 

PUT CCZCPA2) — Complete previous PUT. 

GETPAGE CCZCPI2) — Read data or overflow 
page without outputting old page. 

Interlock CC2COH1) — Lock RESTBL for 
shared data set. 

Release Interlock CCZCOI1) — Unlock 
RESTBL. 

Exits : 

Normal -- Return is to the calling program 

via RETURN macro and with a completion 

code in general register 15. 

Error — 

SYNAD; Error return to the user is by 
using SYNAD exit in the DCB for any of 

the following conditions : 

• Invalid retrieval address. 

«•• Operation was SETL to next, and at end 

of data set (member) - 

• Operation was SETL to previous, and at 
beginning of data set (member) . 



* Key not found. 



ABEND is executed dttet tlu* to 1 lowing 
cases where continuation is not 
meaningful: 



• Invalid code in macro code field ot 
DCB. 

• Attempted 3ETL by retrieval address 
for shared data set. 

VDMEP is called if: 

• SYNAD address in DCB had not been 
resolved. 



Operation : Initialization and general 

register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for the SETL save area and 
CSECT, DCB r DCB header, RESTBL* and data 
page buffer. 

SETL is a "fence sitter/ and has no 
PSECT, It is always called by type~l link- 
age and assumes the same privilege as the 
caller. The SETL save area is obtained 
dynamically by Open Common on a DCB basis. 
SETL has to access the interruption storage 
area (ISA) to determine its current privi^ 
lege state before calling privileged rou- 
tines. SETL will execute type-1 or type- 2 
calls depending on its privilege state. 
The RESTBL is interlocked for shared data 
sets. The lock will be released prior to 
any return. 

If a PUT was in progress, it is com- 
pleted by calling PUT CC2CPA2) . For SETL 
to next, the Current Record switch is 
turned on and the page is read into the 
buffer. The current locator is stepped 
down by 2 bytes . If the current locator is 
equal to end of space (EOS) 9 the next page 
must be read* The current locator is then 
set to X'FFC 8 14092). This process is 
repeated until a data record is found. 

For SETL to previous , the current loca- 
tor is stepped up by 2. If this value 

reaches X f FFC f (4092) the previous page 

must be obtained by calling GETPAGE 
CCZCPI2). The current locator is then set 
to the value in BOS. This process repeats 
until a data record is found. 

Set SETL to beginning r the first data 
page is read in # the current locator is set 
to X'FFC (4092) and a procedure as in 
•"SETL to next" is followed. 

For each of the above, the locator is 
examined; if necessary the specified over- 
flow page will be read into the overflow 
buffer f and the locator (on page or from 
the overflow page) is used to set up the 
retrieval address in the DCB. 
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For SETL by retrieval address, the spec- 
ified record is read in and the program 
exits. 

For SETL by key, a binary search of ttte 
directory is performed. If a directory is 
not present, the first page is assumed to 
contain the specified record. when the 
required page is read in, a binary search 
against the keys associated with that page 
is performed using tne locators found 
there. Overflow pages may be read to per- 
form this search. When the desired record 
is found, the retrieval address is set as 
above and the program exits to the caller. 



Read/Write, DELREC Routine (CZCPE) 

Read/Write is used for nonsequential 
access to a VISAM data set by either key or 
by retrieval address. DELREC is used to 
delete a record by the same criteria. (See 
Chart OD. ) 

Attributes : Read-only, reenterable, publ- 
ic, privileged. 

Restrictions : Cannot expand RESTBL for 
shared data set. Shared data sets cannot 
be read by retrieval address. 

Entry Points : 

CZCPE1 -- Entered via type-1 or type-2 

linkage through expansion of the READ or 

WRITE macro instruction. 

CZCPH1 — Entered via type-1 or type-2 

linkage through expansion of the DELREC 
macro instruction. 

Input : 

For CZCPE1, register 1 contains the address 
of the DECB. The operation will be con- 
trolled by specifications stored in the 

DECB (Table 40) . 

For CZCPH1, register 1 contains the address 
of the DCB. 

Modules Called : 

PUT (CZCPA2) — Complete previous PUT. 

SETL (CZCPC2) — Locate proper record 
position. 

Add Directory Entry (CZCPL1) — Update 
VISAM directory. 

VMA (CZCGA) -- Get (free) a page buffer in 
order to reclaim needed space from a 
data overflow page. 

GETPAGE (CZCPI) ~ input or output of a 
page. 

MOVEPAGE (CZCOC) — Release read interlock 
on data page. 



VDMEP (CZCQK1) -- Output a diagnostic mes- 
sage and terminate the function (but not 
the task) . 



Exits : 
Normal 

Error - 



Return to the calling routine. 



1. Return to the calling routine with a 
return code of X'04' in general 
register 15, followed by c» call to the 
user SYNAD routine, under any of the 
following conditions: 

• READ, WRITE, or REPLACE key not 
found 

« Equal keys found on a write new key 

• Too many overflow pages 

• Attempt to EXPAND shared data set. 

2. VDMEP is called if; 

• No SYNAD address . 

• Update with read-only access. 

• Nonprivileged caller/data set 
privileged. 

• Input key does not match the key in 
the record for a write operation. 

• Unexpected return code from CZCPI. 

3. ABEND is issued if the DCB header does 
not point to the DCB, or if the record 
length exceeds maximum. 

Operation ; Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for the CSECT and PSECT, DECB, 
DCB, DCB header, RESTBL and data page 
buf f er . 

Upon entry to CZCPE1 or CZCPH1, the 
SYNAD indicator in the DCB (DCBEX1) is set 
to either READ/WRITE or DELREC. The RESTBL 
is interlocked for shared data sets. The 
lock will be released prior to any return. 
If the last operation was a PUT, a test is 
made to see if the data set is shared. If 
shared, PUT is called at CZCPA2 to complete 
the previous PUT. If the data set is not 
shared, and the operation is not WRITE New 
Key, PUT is called at CZCPA2. If WRITE New 
Key and the key is not greater than the 
previous key, CZCPA2 is called. However, 
if the new key is greater than the previous 
key, PUT is called at CZCPA1 to place the 
new record with a move mode PUT. 

The type of the requested operation (by 
key or by retrieval address) is determined. 
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and the appropriate code is set in the DCB 
uuicro code field (DCBMCD) prior to calling 
SETL. A check for read-only access is 
made; if so, VDMKP is called. SETL 
(CZCPC2) is then called to locate tha 
desired record. 

SETL returns either found or not found, 
it not found* the key did not exist and the 
operation is assumed to be a WRITE New Key. 

At this point for operations other than 
WRITE New Key , SYNAD is called with a not 
found condition. For a new WRITE, not 
positioned to the end of the data set s a 
locator is inserted in the appropriate 
place, the control information governing 
space is updated to reflect the insc^rtion* 
and the data record is moved. GETPAGE 
(CZCPI) is called to output the page con- 
taining the new record, and control is 
returned to the caller by the RETURN macro. 
if the operation is WRITE New Key, posi- 
tioned to end of data set, and shared, PUT 
is called at CZCPA1 with the PUT option set 
to Move Mode Complete (DCBMCD = X s 0008* K 
if the data set is not shared, the PUT 
option is set to Move Mode (DCBMC1 = 
X'000U f ), Upon return from PUT, control is 
returned directly tc the caller if the data 
st.t is not. snared; if shared, GET PAGE 
(CZCPI1) is called to output the page con- 
taining the n€*w record prior to returning 
to the caller. 

If SETL returned a found condition f the 
operation to be performed is one of the 
following : 

• DELREC 

• READ 

« WRITE Replace by Retrieval Address 

• WRITE Replace by Key 

D i.ItREC Ope rat ion : If the operation is a 
."'*»iete # the locator is removed from the 

page and the remaining locators are com- 
pressed to close the gap made by the dele- 
tion of the locator. The number of bytes 
occupied by the deleted record and its 
locator is added to the recoverable space 
counter and the End of Space pointer is 
updated to reflect the deletion, If the 
physical deletion was performed on an over- 
flow page, the overflow page is written out 
isj calling GETPAGE CCZCPI1), in addition to 
calling GETPAGE to output the data page. 
Tno locator on the data page is cleared 
prior to out putting the page* Control is 
returned to the caller by the RETURN macro* 

READ Operation : For the READ operation, 
the data record located by SETL is moved to 
the user specified area. A test is then 
made to determine if the operation being 
performed is a READ Exclusive (READ KX) . 



It y» s s, control is returned to the caller. 

If n<>t f and the data set is not shared, 

control is returned to the caller. If 

shared, MOVEPAGE CCZCOC) i9 called to 

release the READ interlock on the data 
page. Control is then returned to the 
call er . 

WRIT E Replace _ by Ret rieval Address and 
WRIT E Repl ace by Key Operation : For a 

WRITE Replace p where record length is equal 
to or shorter than the old record, the new 

data replaces the old, recoverable space is 
adjusted, and control is returned to the 
caller. For a WRITE Replace where the new 
record is longer than the existing record, 
the procedure for a Delete is followed to 
adjust available space* Then the record 
will be moved into the available space if 
sufficiently large- If space plus recover- 
able space is not sufficient to contain the 
record , the record will be placed on an 
overflow page where sufficient space 
exists. 

When space plus recoverable space is 
sufficient to contain the record, GETMA1N 
CCZCG2) is called to obtain a 1 page buffer 
and the page (overflow or data) will be 
copied so as to collect available space 
into a single field # thus allowing the new 
record to be inserted. PREEM&IN CC2CG3) is 
then called to release the page buffer. 
Alternatively* a WRITE may cause a page to 
become filled with locators or cause an 
existing record to be moved to an overflow 
page* 

Add Directory Entry will be called to 
update the directory if the last locator on 
the current page must be moved to the next 
page* This process may repeat when pages 
filled with overflow locators are 
encountered. 

GETPAGE Routine CC2 CI l± 

GETPAGE is used by VISAM routines READ/ 
WRITE CCZCPE) , SETL CCZCPC) , VISAM Get 
CCZCPB), and VISAM Put CCZCPA) # to control 
page I/O of a data set or member- It is 
used to bring data or overflow pages of a 
data set into a buffer (or locate them) , 
delete existing pages f add new pages r or 
update existing pages, GETPAGE calls MOVE- 
PAGE to set up the action I/O operation. 
Additionally, GETPAGE releases interlocks 
on the external page entries CCHAEPE) of a 
shared RESTBL, RELEX and ESETL. (See Chart 
OE.) 

Attributes : Read-only, reenterable, publ- 
ic, privileged. 

Entry Points : 

CZCPI 1 -- Output current page, read speci- 
fied page? if page number equals last 
data or overflow, insert one page* 
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CZCP12 -- Input a specified page. 

CZCP13 ~- Dol^tc specified pages. 

CZCPG1 -- Release exclusive control WRITE 
interlock of a page CRELEX). 

CZCPD1 — Release existing READ interlock 
on a page CESETL) . 

Type-1 or type~2 linkage may be used for 
any of the above entry points. 



Input ; Register 1 contains the address of 
the DCB. 

Modules Called ; 

Stow CCZGOK1) -- Update POD for overflow 
page in VPAM member. 

MOVEPAGE CCZCOC1) — Input or output a 
page. 

insert/Delete Page (CZC0D1) — Insert added 

pages or, remove unused pages. (CZC0D2) 
-- Delete page from a data set or 
member. 

Interlock (CZCOH1) — Called by CALL macro 
to lock RESTBL. 

Release Interlock (CZC0I1) -- Called by 
CALL macro to release RESTBL lock. 

WRITEDSCB CCZCEW1) -- Update DSCB for a new 
VISAM overflow page, 

VDMEP CCZCQK1) — Output a diagnostic mes- 
sage and terminate the function Cbut not 
the task) . 

VISAM PUT (CZCPA2) — Complete PUT if that 
was last previous operation. 

Exits: 

Normal -- Return to the calling routine 
with one of the following return codes: 



•OO" 
f 04 f 



Normal. 

Insert required, DC BIO switch 
not set for input. 



*0C f Maximum overflow pages exceeded. 

•10 s Return code of • G** s received 
from MOVEPAGE (CZCOC1K 

f 14" First attempt to assign overflow 
page with no external space 
available* 

Error ~ VDMEP is called under any of the 
following conditions: 

* Incorrect page number on attempt to 
insert page. 



• No external space available. 

• Storage ration exceeded. 

• No secondary storage allocation. 

• Attempt to expand shared data set. 

• J4aximum data set or member size 
exceeded. 

• Attempt to insert or delete beyond end 
of data set. 

• SYNAD f but no SYNAD address in DCB. 

• Invalid return code from CZCOD 
C Insert/Delete Page) . 



Operation ; The several entry points serve 
processing as follows: 



CZCPI1 and CZCPI2 ; Initialization and gen- 
eral register storage is executed in con- 
formance with linkage conventions. Base 
registers are declared for the GETPAGE 
CSECT and PSECT f DCB ff DCB header and 
RESTBL. 

Entry flags are set to indicate which 
entry point was called. CZCPI1 effects the 
outputting of the current page before per- 
forming the input of the requested page. 
CZCPI2 effects the inputting only. 

GETPAGE may be entered to insert a new 
page in the data set. Insert/Delete Page 
CCZCOD1) is called to insert the page. 
WRITEDSCB will be called to update the DSCB 
if a new overflow page is being inserted. 
The page is initialized to VISAM format and 
control is returned to the caller by the 
RETURN macro. 

For a new insert which has a page cur- 
rently in the buffer, a call is made to 

MOVEPAGE to output the page if GETPAGE was 
entered at entry point CZCPI1. 

Also, if it was a pure output request, 
control is returned to the caller by the 
RETURN macro. 

For a noninsert entered at entry point 
CZCPI2 f or entered at entry point CZCPI1 
for other than output, a test is made to 
determine if the buffer is empty* If not, 
and if the data set is shared, MOVEPAGE is 
called to effect the input of the requested 
page* If nonshared, and if the page Cdata 
or overflow) is already in the buffer , con- 
trol is returned directly to the caller. 
If the page is not in the buffer, MOVEPAGE 
is called to effect the input of the 
requested page. 
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CZCPXi i Entry is made at CZCPI3 to delete 
pages fro® a VXSAM data set. Insert/Delete 
Page ICZCOD21 is called to perform the 
physical deletion. The noaiber of data, di- 
rectory, and overflow pages are updated to 
reflect the deletion* Control is returned 
to the caller by the RETURN macro. 



CZCPDt an d CZCPG1: Indicators are set to 

release read or write interlocks. If the 
Ust operation was a PUT, POT CCZCPA2) is 
called to terminate the previous PUT* The 

call to 'PUT causes a call to MOVEPAGE which 
will release the indicated interlocks. 
Control then returns to the caller* 

It the last operation was not a POT„ 
control is passed just beyond the C2CPI1 

cirsd CSCPK' entry points* Hie resulting 

calls to MOVEPAGE will reset the indicated 

interlocks. 



> At e - 1 oc ■< Ha n dl i ng ; GETPAGE will, upon 

getting a request to input a page, test if 
that page in a data page or an overflow 
page. For an overflow page, it will input 
the page, since overflow pages are not 
interlocked- For a data page # GETPAGE will 
check if there Is a data page interlock 
currently imposed. If so, it will deter- 
mine if a read or write lock is set, and 
call MOVEPAGE with the appropriate option 
to release the lock. It will then input 
the requested page. If MOFEPAGE returns to 
GETPAGE with a return code stating that the 
-gage was locked and could not be input, 
GETPAGE will set a return code, and exit, 
indicating the page was not input* 



A.dd Directory Bnts y Routine (CZCVL) 

Add Directory Entry is used to change 
contents of a VISAM directory due to added 
or deleted pages, which niay cause the size 
of the directory to change. It also 
changes the key value when a change is made 
to a record that does not cause the number 
of data set pages to change- CSee Chart 
OF.) 

?'*lSzL}J^S:f2L : Read-only, reenterable, publ- 
ic, privileged. 

Restrict ions; The directory of a shared 
.lata set may not be expanded, 

lC:i'£M,J±.2l^J CZCPL1 -- Entry to Add Direc- 
'•^••-y Entry is by type-1 (privileged to pri- 
vileged), or type- 2 (nonprivileged to pri- 
vileged) linkage. 

Input : Register 1 contains the address of 
the DCB for the member whose directory is 
to be updated . 



Modules Cajled s 

GETMAIM CCXCG2) « Obtain one page of vir- 
tual storage for initial directory 
entry. 

Expand CCZCGH) -- Increase space assigned 
to the directory area. 

Insert/Delete Page CC2C0D1) — Insert added 
directory pageCs) into RESTBL* CCZCOD2) 
— Delete pageCs) no longer needed in 
directory* 

VDMEP CCZCQKl) ~ Output a diagnostic mes- 
sage and terminate the function (but not 
the task). 

Exits, : 

Normal ~ Return is to calling program 
using the RETURN macro. 

Error — ABEND is called for the following 
conditions s 

• Current page number greater than numb- 
er giwen in DCB. 

• Attempted add beyond end of data s#-*t, 

• NuaJber of directory keys not properly 
cooputed* 

VDMEP is called (the function is ter- 
minated) under any of the following 
conditions : 

• Maxiauai directory size exceeded. 

• No external storage space available, 

• Storage ration exceeded. 

• No secondary storage allocation 
specified* 

• Expanding directory of shared data 
set, 

• Insertion beyond end of data set. 

• Deletion beyond end of data set. 

• Maximisa data set size exceeded. 

• Invalid return code from CZC0D. 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for the CSECT and PSECT, DCB f 
RESTBL and DCB header. 

If one or no data pages exist, no keys 
are placed in the directory and control is 
returned to the caller by the RETURN macro. 

If keys are to be taken out of the di- 
rectory as a result of the deletion of data 
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pages, the keys are removed; if any direc- 
tory pages are vacated due to key removal, 
they are deleted from the data set by cal- 
ling Insert/Delete Page at CZCOD2. The 
number of directory pages is updated and 
control is returned to the caller by the 
RETURN macro. 

If a data key is to be added to the di- 
rectory, and no directory pages exist, vir- 
tual storage space is obtained by calling 
GETMAIN* The directory page is logically 
inserted into the data set by calling 
Insert/Delete Page at CZCOD1* The newly 
obtained directory page is initialized. 



The number of keys in 
computed. The number of 
tory must be equal to or 
rent data page number min 
that the call is to chang 
current data page number 
than the number of keys, 
since an attempt is being 
beyond the end of the dat 



the directory is 
keys in the direc- 
less than the cur* 
us 1 , which means 
e a key. If the 
minus 1 is greater 
ABEND is called, 

made to add data 
a set. 



If a new key is being added, the last 
directory page is checked to see if enough 



room exists to hold the key. If no space 
is available, and no assigned but unused 
directory pages exist, the directory is 
expanded (CZCG4) providing the data set is 
nonshared. If shared, VDMEP i: called. 
For the nonshared data s<^t f a (heck is made 
to determine if more than one [*CB has been 
opened for the data set; if so, all are 
linked to the same ISD and SISD buffer 
page. The new directory page is initia- 
lized and logically inserted into the da to. 
set by calling Insert/Delete Page at 
CZCOD1. Processing continues as if a new 
key were being inserted or a key being 
changed. The key is moved to the directo- 
ry. If a new key is being added, a new end 
of directory is computed. 



The ISD Integrity flaq in the RESTBL i:* 
set? this indicates to VSAM CLOSE (CZCQA) 
that it should write the ISD to external 
storage. 



Control is returned to the caller by the 
CALL macro. 
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lCVION 7: 



VIRTUAL PARTITIONED ACCESS METHOD CVPAM) 



The pri r t i t ion«Hl < >i qan izat ion of the vir- 
t u/.i i ,jcc(':;:j met hod uses both sequential and 

md^x siH]uont ial organiz.itions to procfsr. 
oat a set members. Thin method uses macro 
instructions and routines to combine VSAM 
and VI SAM data sets into a single data set 

a s a s er i e s o f log i ca 1 pa r t i t i ons . To d ea 1 
with the complexities associated with this 
access method, TSS/360 uses a partitioned 
organization directory (POD) and relative 
page/external page correspondence table 
(RESTED, The POD and the associated data 
control block (DCB) ate used to relate a 
member, or its alias names, to the relative 
position, of l be membrr within the data set. 
The RESTBL is used to determine the actual 
external device address of the requested 
pageC s) . 



The following contribute to the virtual 
partitioned access method (VPAM) . 



V: r :. i Ccd, : s _ Macro;;; 

DCB Supplies parameters to define 

member: structure and attributes, 

FIND Requests access to a n>ember 
descriptor from the POD. 

STCM Specifies updating of a member 

and/or alias descriptors in the 

POD, 

Control Blo cks 

DCB D'.ta control block - 

o 'ganizat ion™ independent working 

s 4 orage. 

RESTBL Relative external storage corres- 
pondence table. 

POD Partitioned organization 
directory. 

Gene r a 1 VPAM Ro ut i ne s 

Find 



Stow 



?arch 



Extend 
POD 



Locates member descriptor in POD. 

Updates member and/or alias 
descriptors in POD. 

Searches POD for member or alias 
name* 

Increases size of POD. 



Relocate Updates the POD to account for 
Members in size of the POD or any member 
of the data set. 



GETNUMBP Gives page number of a member 

relative to the data set, based 
on starting paae number of the 

member • 



VJIA-M CONTRO L BLOCKS 

The POD and RESTBL member header are 
described below. 

Partitioned Organization Directory CPOD) 

The POD f which consists of pageCs) at 
the beginning of a VPAM data set is placed 
in the user's virtual storage by OPENVAM at 
data set OPEN time. The POD page Is) are 
provided and maintained .by VFJ^M for each 
partitioned data set* Its function is to 
document member names with their relative 
locations within the data set and their 
attributes (data set organization, number 
of pages § user data field). The POD also 
documents all aliases assigned to the 
various members of the data set. 

The maximum size of a partitioned data 
set is 65 p 535 pages; the maximum size of 
ail members or even a single member is 65, 
53 4 pages. When the data set is shareable, 
the POD is placed into shared virtual 
storage and protected from the user. 

The directory f Figure 27 , is divided 
into four parts; each POD part provides a 
particular function* The four parts are as 
follows: 

1„ An interlock control entry, 

2* A space control entry* 

3. A directory block hashing table, 

4* Directory block entries linked into 64 
chains. 

The interlock word and the procc?dures to 
update same are described in the module 



r „_„____„„„_. , .„„. ___. — .„„„ 1 

j Interlock Control (U bytes) j 

H „____ „„___„„__„_4 

| Space Control (8 bytes) j 

H . _ -_„„___„_„__„ H 

1 Hashing Table C256 bytes) | 

!„-_„-„ .__ ._„______, 

| Linked Block Entries (variable length) j 

Figure 27. Partitioned Organization Direc- 
tory CPOD) 
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descriptions fur VAto general services rou- 
tines Interlock (CZCOH), and Release Inter- 
lock (CZCOi). 

The ii pace control entry (PODSPA) indi- 
cates the number of pages in the POD and 
the number of paqes in the data set (Table 
US) . 



VPAM ROUTINES 

Descriptions of Find, Stow, Search, 
Extend POD, Relocate Members, and GETNUMBR 
follow. 



Find Routine (C2COJ) 



The hashing table (PODHT) contains 6 4 
pointers (each four bytes in length to the 
member and alias descriptors. The hashing 
value of a member name or alias causes 
selection of one of the 6*4 pointers, which 
in turn contains the byte address relative 
to the POD, of the linked block entry 
corresponding to the first name having that 
nashing value. This block entry then 
points to the word address relative to the 
POD, of the second name having that hashing 
value, etc. 

Linked block entries are of two types: 
member descriptor entry and alias descrip- 
tor entry . A member descriptor entry is 
defined in Table U6„ 



An alias descriptor is defined in Table 



47. 



Use of Member Headers in RESTBL 

For partitioned data sets only, a field 
(DHDLNK) in the DCB header CDSECT name: 
CHADHD, Table 48) of the RESTBL, points to 
the member header CCHAMHD) rather than to 
the RESTBL header. The RESTBL member head- 
er gives additional data needed to locate 
pages within a member. 



Find searches the POD in order to locate 
the member descriptor. The member informa- 
tion including the starting page number and 
RESTBL header offset is transmitted to the 
member header and the associated DCB- (See 
Chart PA.) 

Attribute s: Read-only, reenterable, privi- 
leged, public, system. 

Restrictions : A DCB can refer to only one 
member at a time* STOW must be issued to 
change user data in the POD prior to issu- 
ing a FIND. The DCB must be opened before 
FIND is executed* 

Entry Point : CZCCJ1 — Via type-1 or type- 
2 linkage. 

Input s On entry, general register 1 con- 
tains the address of the following four- 
word parameter list: 

Word 1 — Address of DCB. 

Word 2 — Address of member name or alias. 

Word 3 — Address of area where user data 
is to be placed. 

Word ** — Address of member of bytes of 
user data. 



Table 45. POD Format 
I Bytes J Symbol | Contents 

| PODW 



^ 



1 
2 
3 

14-5 
6-7 



1 
|PODR 

I 

| PODRC 

I 

| PODIC 

I 

I 

1 PODPG 

I 

1 PODNDP 



8-B |PODLBP 

1 

I 

I 
C-10BJPODHT 

I 

L JL X, 



Write interlock 

Read interlock 

Read interlock counter 

Control bytes for PODR and 
PODRC 

Number of pages in POD 

Number of pages in data set, 
including POD pages 

Linked block pointer, 
pointer (relative to POD) of 
next available byte in POD 

Hashing Value Table 256 
bytes 

J 



Modules Called : 

Stow (CZCOK1) — Stow member already 
checked out to his DCB. 

CKCLASS CCKCLS) — Check protection class 
of user area and DCB for compatibility. 

VDMEP (CZCQK1) -- Process error occurring 
while trying to access locked member 
header. 

Search CCZC0L1) — Locate member or alias 
descriptor in POD. 

VSAM Open CCZCOP1) — Initialize for 
sequential organization. 

VISAM Open (CZCPZ1) — Initialize for index 
sequential organization* 

Interlock CCZCOH1) — Impose interlocks on 
RESTBL for shared data sets. 

Release Interlock CCZCOI1) — Release 
interlocks on RESTBL for shared data 
sets. 
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Table H6. POD tM ember U^rjcriptor 
(Part 1 of /> 



r - T .. — - T . 

fSymboii Ddta| 

f POHNAM 
I 



Fie id l ef Lnilion 



iPGMFLG 



POMHAS 



, POMFP 



I POMPG 



1 



| POMSEQ 



I 



1POMKL 



I 



S POMXX 



W # X 



The member nanie, 
left -adiu'Jt od and paddod with 
blanks, it tn'cesudry. Koi a 
deleted out ry # each byte of 
this field is set to x'FF'. 

Bit 0=1 to indicate that this 
is a member descriptor. 
Bit 1=0 indicates that no 

user data is appended. 

Bit 1=1 indicates that user 

data is appended- 

Bits 2-7 are presently not 
used. 

Bits 0-10 contain a pointer 
to the next descriptor whose 
name is a hashing synonura to 

the member name. This field 
points to the relative 

full word upon which the next 
hashing synonym descriptor 
exists, or is zero if no such 
descriptor exists. 
Bits 20-21 indicate the 
organization of the member: 

00 Sequential 

01 Index Sequential 
Bits 22-23 indicate the 
record length format of the 
member : 

00 Variable 

01 Fixed 

10 Undefined 

First page of this member 
relative? to data set. 

Number of data pages in this 
member . 

Sequential member - record 
length (actual or maximum) 

Length in bytes of the keys 
for an index sequential 
member. 

Bits 0-11 - length ol the 
logical records for <. member 
with fixed length lot, icai 
records, the maximum logical 
record length for an index 
sequential member with 
variable length records. 

Bits 12-23 - relative 
position of the key within a 
logical record of an index 
sequential member. 



Table U6- POD Member Descriptor 
(Part 2 of 2) 



r T T 

f Symbol | Iiata | 



Field Definition 



h 



-+- 



POMOV P I N 



POM I, D 



POMDf 



POMBl' 



POMUSE 



N umbe i ot overt i ow pa cj t^s 

only) . 

Pad percent ago tor index 
sequential pages. Maximum 

value is 50. 

Number of directory pages , 
index sequential member, or 
number of unused bytes in the 
last data page for a 
sequential member. 

Number of bytes of user data 
contained in next field; this 
field and following field 
will be absent if bit 1 of 
POMFLG is 0. 

Optional data to be supplied 
by the user* Length of this 
field is specified by POMBU. 
For object program modules , 
this field describes the 
relative (to the member) 
locations of the internal 
symbol dictionary. The next 
descriptor will begin at a 
word boundary regardless of 
the length of this field. 



SETL (CZC0T1) (VSAM) -- Position DCB to 
beginning or end of VSAM member. 

SETL CCZCPC2) C VIS AM) -- Position DCB to 
beginning or end of VISAM member. 

Expand RESTBL CCZCQI1) — Expand RESTBL by 
1 page to accommodate new member header. 

TSEND (CEAP7) — Function is executed while 
waiting to access user counter in member 
header. 

CLOSEVAM CCZCOB1) -- Close member header if 
open on a STOW- type D. 



Exi t s; 

Normal -- Return is made to the caller with 
a completion code in general register 
15. If the user area and size were 
unspecified in the calling parameter 
list, the location and number of bytes 
of user data in the member descriptor 
(POD) are returned as words 3 and a of 
parameter list addressed by general 
register 1. 
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Table 47. POD Alias Descriptor 

r r t 1 

| Symbol | Data j Field Definition | 

POENAMf C |The alias, left-adjusted and 
padded with blanks if 
necessary. For a deleted 
entry, each byte of this 
field contains X'FF". Y. 
For a deleted entry, each 
byte of this field contains 
X f FF f . 

POEFLG| X |Is zero (high-order bit being 
zero indicates that this not 
a member descriptor) . 

PQFHASf W |Bits 0-19 are a pointer to 
the next descriptor whose 
name is a hashing synonym to 
field 1. This field points 
to the relative fullword 
containing the next hashing 
synonym descriptor, or is 
zero if no such descriptor 
exists. 

Bits 20-23 are zero. 

POEMEMl B [Pointer to the member 

descriptor for which this 
entry is an alias (byte 
address relative to the POD) . 



Return codes? 

s 00' Member or alias found and member 
opened. 

•0*4* Member name or alias not found. 



'08* The DCB is creating a member ~ A 
STOW-N must be issued for member 
being created before this DGB can be 
used to FIND a member. 



Table U8. RESTBL Member Headers (CHAMHD) 



| Symbol] Data | 



Field Description 



— . — 4 

MHDNAM 


? 1 


MHDFEP 


W | 


MHDDIR 


N | 


MHDDAT 


N | 


MHDOVF 


N | 


MHDBYT 


N | 


MBDFLG 


X | 


MHDINT 


L I 


MHDUSE 


N | 


MHDVAL 


X i 


MHDNMH 


D 1 


MHDPMH 


[ D 1 



Member name 



-H 



Offset to first external pagej 
entry of the member | 

Number of directory pages 
(index sequential 
organization only) 

Number of data pages in the 
member 

Number of overflow pages 
(index sequential 
organization) 

Number of bytes used in last 
page of sequential 

organization 

Flag to indicate sharing 

status and organization 

X f 80» Shared 

X f 20 f Index Sequential 

Interlock byte to protect 
number of users and chain 
link fields 

Number of users associated 
with this member 

Value of first external page 
entry in the RESTBL of the 
member 

Chain to next member header* 

Chain to previous member 
header* 

A, .J.. . . . . _. 

|*This value gives the relative location 
within the RESTBL by multiplying by 8 
Cleft shift 3 bits). 

L . . .— . . . , . . . .„- . .J 



r 



'0C' Data set organization in member 
descriptor does not match DSORG 
specified in DCB. (Can only occur 
if DCB specified VIP or VSP and mem- 
ber descriptor did not match; if VP 
was specified in DCB, Find fills DCB 
in with DSORG found in member 
descriptor. ) 

'10' The user area length is not large 
enough to contain the user data to 
be retrieved. 

*!<*• Member to be located has already 

been checked out to this DCB. (Mem- 
ber has been previously found.) 



FIND calls VDMEP if: 



1. While waiting to access locked member 
headers, an Attention is received. 



2. While waiting to access locked member 
headers, 100 TSENDs are completed. 

3. The DCB is found to be closed or 
invalid. 

4* The DSORG is invalid. 
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'or -- ABEND will tn executed upon 

detecting -my of t h" following 
eond it)' ms ; 



B I^Mdr r >]r 



<jt point to dcb. 



• RKTBL of i shared data set requires 
exj dnr.ion. 

• Error rot urn tr».»m SRCHSDST call. 

• K r r o r return front S T Or/ c c » 1 1 . 



Tii'- -tci i vo fnt\r»:>oi header chain in t iu 
RESTBL ir< :;^archH to spp if the member is 
already in use by .mother DCB. If the mem- 
ber is ^<yr..ive a t ^:-,t is made to see if it 
is wr i r. e-i nt er locked. This means that the 
member is currently being modified and is 
unavailable for us*--. A time-slice end ™ : s 
requested via TSEND. At tne resumpt ion of 
the user's, task, the FIND has to be re- 
initiated, since the other user may have 
deleted the member or chanqed its name 
while it was interlocked. 



• The protection classes of the DCB and 

us e r a r ea a r e i no om pa t i b 1 e . 

• DCB Header not linked to meir.be l header. 

• VPAM member header locKed, wit!; no 
a o 1 1 v e DC B t I e a d e r . 

• In valid member or alias n^rne 

•• p- cif ied. 

'^r * Lei 3 ilA 9D : Initializa t ion and qptk -■ r a 1 
register storage is executed in conformance 

with linkage co n v e n t i o n s * B a s e regi s \ e r s 
are declared for the Find CGECT and PSECT, 

DCB, DCB header, RESTBL* member header and 
POD. 

Upon entry, if t ht- DCB header does not 
[ >o i n t t o t h * > DC f ; ! , A BEND i s ca lied. 

The RESTBL is wr ite- inter locked for 

j j h a r e d d a t a s e t s „ 

The DCB is tested to determine if it is 
currently in use. If a member had been 
found previously and was still checked out 
to tne DCs, Find calls r»tow (H ) to close 
the member. If the DC! 1 is in use for 
or ea ting « m ember , the call t o Find ma y 
have been done erroneously. A return is 
givt-n tn the caller indicating that the DCB 
is in use ror creating a member. This 
allows the user to name and stow the member 
and saivaqe the work he has done which 
could have been lost from an erroneous call 
to Find, since the member being created was 
unn earned. 

1L The DCP is rot in use, the POD is 
searched for tne name given to Find. If 
t n e n a me c a n n ot. b e located in the POD, a 
"not found* return is made to the caller. 

if the found name was an alias, the 
cor responding member name is located. 

User data is moved to the user area if 
it was specified. 

Where more than one DCB is open for out- 
put for a nonshared member, all DCB headers 
are linked to the same member header and 
flags are set to indicate the data set may 
not. be written cut. 



if the member was active, the DCB header 
is United to the active header. Dummy 
header space is placed i.n the deleted head- 
er chain if it existed. 

If the member was not active, a member 
header has to be built. It can be built in 
the dummy header space provided by OPENVAM # 
in available (deleted header) space, or it 
can be built in unused RESTBL. A dummy 
header will exist if this is the first call 
to Find since OPF.NVAM was executed. If a 
FIND was done and tlv? DCB header was linked 
to an active member leader, the dummy head- 
er space was released. Subsequent FINDs 
will use the deleted header space, if 
available, or unused RESTBL space. If 
unused RESTBL space is required and there 
is not enough space remaining to accommod- 
ate a member header, the RESTBL is expanded 
by calling Expand RESTBL CCZCQI) (non- 
shared data set onl>). 

After the member header is built, data 
set parameters are filled in the DCB from 
the POD. 

If directory panes exist (VISAM) , GET- 
MAIN (CZCGA), is called to obtain virtual 
storage space and the directories are read 
in by calling COVERAGE (CZCOC). 

The data set orgmization CDCBDSO) is 
rested. If VSAM or VISAM partitioned, 5ETL 
is called, de ;endini on the Open optaon to 
logically position the members for proces- 
sing. If the DSORG is "non-specified 98 
(VP) , tne data set organization is obtained 
from the POD and the appropriate access 
d e pe nd ent open r oa tine i s ca 1 1 e d * 

The RESTBL interlock is released for 
shared data sets, and control is returnee] 
to the caller by the RETURN macro. 



Stow Routine (CZCO? )_ 

Stow is used to modify, add, or delete 
member or alias descriptors in the POD. 
The RESTBL will also be updated as 
required. Stow also updates the user data 
field in the member descriptor. (See Chart 
PB. ) 
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Rend-only, reenterable, privi- 



Attr ib utt, ? 

leged, public, system. 

Restrictions : Each member and alias name 
within a VPAM data set must be unique. 

The DCB used to control opeiations on a 
member must be open prior to issuing a 
STOW. 

If a type~N STOW or type-R STOW is given 
for a member, subsequent references to the 
same member must be preceded by a FIND. A 
FIND must be issued before attempting a 
STOW CR) f (U) , or (D) . 

If new aliases are being added to an 
existing data set, no duplicates are 
allowed within the input list of new 
aliases. 

Entry Point : CZC0K1 — Called by either 
type-1 (privileged to privileged), or type™ 
2 Cnonprivileged to privileged) linkage. 

Input : Parameters are passed to Stow in 
general registers as follows: 

Register — Address of the user supplied 
data area. The formats will be inter- 
preted, depending on the type of STOW 
issued. They are described with the 
STOW macro format. 

Register 1 — Address of the DCB. Note 
that the macro code field in the DCB 
will be preset to one of the values 
Chex) discussed with STOW macro format. 

Modules Called : 

CLOSEVAM (CZCOB1) — Close member header if 
open on a STOW type-D. 

Search CCZCOL1) — Search POD for a member 
or alias name. 

Search SDST (CZCQE1) — Search shared data 
set table. 

Interlock CCZCOH1) — Impose read or write 
interlocks on POD and RESTBL. 

Release Interlock (CZCOI1) — Release read 
or write interlock on POD and RESTBL. 

Reclaim CCZCOGl) — Release external pages. 

Relocate Members (CZCON1) — Updates POD 
after call to RECLAIM. 

Extend POD CCZCOMl) -- Expand POD by page. 

VSAM Close (CZC0Q1) — Close VSAM member. 

VISAM Close (CZCQA1) — Close VISAM member. 

GETMAIN (CZCG2) — Obtain storage for the 
alias list. 



FREEMAIN (CZCG3) — Release virtual 
storage. 

Expand (CZCG4) — Obtain additional conti- 
guous storage for the alias list. 

Disconnect CCZCGA) — Loqically disconnect 
a task from an area of virtual storage. 

VDMEP CCZCQK1) — Output a diagnostic mes- 
sage and terminate the function (but not 
the task) . 

Find 1CZCOJ1) — Search POD to locate a 
member descriptor. 



Exits : 

Normal -- Return with one of the following 
codes in register 15: 

f 00 s STOW successful. 

• OU • New name, or replacement for old 
name, already in use (N, NA, c f 
CA) f or old alias does not belong 
to member specified* 

•08 f Member name not in POD. 

•10 f Old member name not in POD CO, 
or alias name not in POD CCA, 
DA) . 

•14 s Illegal STOW type requested 

- Macro code out of range. 

- Name specified is all FFs. 

- Input area not on FW bound- 
ary. 

- STOW (NA) and alias count=0. 

f 18 f User data exceeds maximum length. 

s 20 f Attempt to expand POD for system 
catalog. 

Error • — ■ When any of the following errors 
are detected, the ABEND procedure is 
executed to terminate the task: 

• DCB header does not point to DCB. 

• DSORG in DCB is not VIP or VSP. 

• Type-R STOW, member name not found # 
and not called by ABEND. 

• DCB already opened for another member. 

• A call to Search SDST gave an error 
return. 

• Member checked out by another DCB. 

• DCB not linked to specific member. 

• Member in use? cannot delete it. 
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WjvfT) *ju'f f> i* * J i * - .* c .lowing » r;or'. i .i ore 

d^'tf'Ct^'d. ,4 VDMEJ i'i Pxoc.iit.pd .-in-""? th« 
function Inn; the tack) i :.; tornran'^^J: 

• fu-nd- on £ y acces. . 

• No extPinii storage space. 

• Stora qe ration exceeded. 

• No secondary allocation. 

• Attempt, to expand RESTBL for shared 
data set . 

• Maximum data set size exceeded. 

• POD/RET 7 ri h a, i : .ma t c)i . 

• Maximum directory size exceeded. 

• Invalid return code from CZ COM or 
C2COG (will aire: cause SY5ER). 

•♦ Duplicate input STOW NA or NAR. Inva- 
lid oi closed dob passed as parameter. 



( ^lil_i- "4JL is^f 1 * I n l t i a 1 } z a 1 2. c n and ije n e r a 1 
register s t o r a i e i ; » t > x ee i > t e d i r * c o nf o mia n c r t 
with linkage convent ions . Base registers 
are declared for the Stow CSECT and PSF.CT* 
ISA*, DCB, DCB header, m ember header, and 
POD. 

The validity d trie .STOW type, and the 
validity of part teas a r types of STOW witn 
the existing OPEN options, are verified. 
ABEND is called if any errors or inconsis- 
tencies are found. 

The KESTBL is interlocked for shared 
aata sets. The lock will be released prior 
to any RETURN VSAM CLOSE CCZCOQ) or VISAM 
CLOSE (CZCQA> are called if required. 

The POD is searched to locate* the member 
descriptors _f the member name is not 
round in the ^D, a member descriptor is 
built for a t/pe~N STOW. The POD and 
RESTBL page counters are updated to reflect 
the addition of the new member and to 
reflect chang ?s to all CPENed members. If 
the POD has D?en updated by STOW, the POD 
Integrity fla? in the RESTBL is set; this 
causes CLOSEVAM (CZCOB) to write the POD to 
external storage. Control is returned to 
the caller by the RETURN macro. 

If the member name is found in the POD, 
processing continues for the particular 

STOW type: 

• Type-N -- If a name was found on a type 
N (new member), no further processing 
Is done, and return is made with a 
return cede signifying that the new 
name was not unique* 



Type-NA -- New aliases may be added to 
<\n exist mg member. The POD is 

searched for each alias beinq added. 
If the aliases are unique, an alias 

descriptor is created for each alias 

being added. These new alias descrip- 
tors are linked to the appropriate mem- 
ber descriptor, and control is returned 
to the caller by the RETURN macro. 

Type-R -• - STOW type-K is odled to 
replace user data, and close the mem- 
ber, if user area was specified, the 
user data is stored in the POD. This 
may cause the member descriptor to be 
moved, since it may not previously have 
contained user data, or the new user 
data requires additional space. If the 
member descriptor is moved, the hash 
pointers and the alias links are 
updated. If the user count in the mem- 
ber header is zero, the member header 
is closed, (that is, the member header 
is added to the deleted member header 
chain, the OCR header link is cleared, 
and the member name is se-t to 
eXLl'FPM. The POD is updated, and 
control is returned to the caller by 
the RETURN macro. 

Type-0 — Type-U STOW accomplishes the 
same thing as type-R, except that the 
member header is not closed- It 
remains active for further processing. 

Type-D -- STOW type-D (delete) causes 
the data pages associated with a member 
to be deleted by calling Reclaim 
CCZCOG) . The member and alias descrip- 
tors are deleted from the POD. The DCB 
is initialized for reuse, and control 
is returned to the caller by the RETURN 
macro. 

Type. -DA - — Aliases may be deleted from 
an existing members The POD is 
searched for the alias being deleted. 
If found, the alias descriptor is 
deleted from the POD. This process is 
done for e*ch alias being deleted. 

Type-C and Type-CA -- Type-C and -CA 

STOW are name changes of members or 
aliases. The POD is searched for the 
name being changed. When found r the 
new name member or alias replaces the 
old name accordingly. 



Type-NAR -- New alia 
an existing member a 
but if any new alias 
ing aliases or names 
and a list of these 
lied to the caller. 
MAIN for VMA of list 
register and will 
area. If there are 
within an Input list 



ses may be added to 
s in a type-NA STOW 
es duplicate exist- 
none are stowed 
duplicates is supp- 

Stow does a GET- 

passes VMA in 

not FREEMAIN this 

duplicate aliases 

of new aliases 9 
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some aliases may be stowed and, 
although a return code of *04 f will be 
set, no duplicate names will be supp- 
lied the caller (see Restrictions). 



Search Routine (CZCOL) 



Search is called by Find, Stow, and GET- 
NUMBR to locate a member descriptor in the 
POD for a given member name or alias . 
MOSEARCH, entered at Search's second entry 
pointy may be used to search past the first 
matching entry in the POD for additional 
entries with the same name. (See Chart 
PC. ) 

Attributes : Read-only, reenterable, privi- 
leged, public, system. 

Restriction : If MOSEARCH is called. Search 
must have been called first, and the 

results of that search left undisturbed. 

Entry Points ; 

CZCOL1 — altered via type-1 linkage to 

locate first matching member descriptor. 

CZCOL2 -- Entered via type-1 linkage to 

search past first matching entry in the 
POD, seeking additional entries with the 
same name. 

Input : General register 1 contains the 
address of a two-word parameter list: 

Word 1 — Address of the DCB associated 
with the POD to be searched . 

Word 2 — Address of an 8-character field 
containing the member name or alias to 
be used as a search key. 

The search code field in the DCB will 
contain a code to indicate the type of 
search being requested: 



M 

A 

E 



Member 
Alias 

Either 



Error -~ None, 

Operatio n: Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for the CSECT, DCB, DCB head- 
er, POD, and POD member descriptor. 

The DCB is modified per results of 

Search or MOSEARCH; 



DCR 

Sy mbol 

DCBHV 

DCBSC 



DCBSP 



Description 

Hash value of member or alias. 

Relative location within POD of 
found descriptor. 

Relative location within POD 
descriptor of preceding found 
descriptor in same hash chain. 



Search has two entry points. CZCOL1 is 
the entry point for the initial call to 
Search. CZCOL2 xs the entry point for con- 
tinuing Search (MOSEARCH), after Search has 
initially been called. A switch (DCBSWT) 
is set to indicate that the current entry 
was to Search (CZCOL1) . This switch is 
tested on every entry; if on, the member 
name is hashed; if off, the name is not 
hashed, since it was hashed on the initial 
entry and the value still exists in the DCB 
(DCBHV) . 

The hash value is used to obtain the 
hash chain pointers from the POD. If the 

pointer is zero, the return code is set to 
"no hash chain", and control is returned to 
the user by the RETURN macro* 

if the hash chain pointer exists, the 
descriptor is obtained* The name input to 
Search is compared to the descriptor name. 
If the names do not compare, the rest of 
the chain is searched in the same manner 
until the name is found or the end of the 
chain is reached. If the end of the chain 
is reached and the name is not found, the 
return code is set "not found*" and control 
is returned to the caller by the RETURN 
macro. 



Modules Called: None. 



Exits: 



Normal -- Register 15 contains one of the 
following return codes: 

■00" Successful. 

s 04" Entry with matching name and type 
not found — ■ no hashing chain for 
hash value. 

*08 s Entry with matching name and type 
not found — - hashing chain exists 
for hash value. 



If a descriptor name is found that 
corresponds to the Search input name.!, the 
search type (member, alias, or either) i:; 
tested to determine if the found descriptor 
is the correct type. If the search type 
was "E" (either) , the search was success- 
ful, and the return code is set to "found." 
The location of the last two descriptors 
are saved (for MOSEARCH) and control is 
returned to the caller by the RETURN macro. 

If the search type was "M" (member) , and 
the found descriptor is a member descrip- 
tor, a "found" exit is made as described 
above. If the search type was "M" and the 
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found descriptor is an alias, the search of 

the hash chain is continued* 

If the search type was w h m (alias) and 
the found descriptor is an alias, a "found 18 
exit is taken as described above; other- 
wise, the hash chain search is continued. 



Extend POD Routine CC2COM) 

Extend POD is called by Stow to expand 
the POD by one page* both in virtual 
storage and on the external storage device. 
(See Chart PD.) 



Attribu tes : Read-only, reenterable, privi- 
leged, public, system. 

Re strictions : It is not possible to expand 
shared data tables. If this becomes neces- 
sary, a return code is passed to the caller 
and this function terminates. 

Entry Point : CZC0M1 -- Type-1 linkage 
(privileged to privileged)* 

Input : Register 1 contains the address of 
the DCB associated with this POD, 

Modules Called : 

Expand CC2CG*4> ~~ Expand the size of the 
virtual storage area containing the POD. 

Insert CCZC0F1) -- Insert external page en- 
try into RESTBL. 

Relocate Members CCZCON1) — Adjust member 
page numbers to compensate for expanded 
POD. 

VDMEP CCZQK1) — Output a diagnostic mes- 
sage and terminate the function (but not 

the task) . 

Exit s : 

Normal — Return to the calling routine 
with one of the following return codes: 

s 00* Normal. 

•Oil" No storage space available. 

*08 f Storage ration exceeded* 

S 0C* No secondary storage allocation 
specified, 

f 10 s Shared data set RESTBL cannot be 

expanded. 

•14* Maximum data set/or member size 
exceeded. 

'18' Insertion beyond end of data set. 

• 1C* Deletion beyond end of data set. 



Error — VDMEP is called if an invalid 
return code is received from Insert . 

Operation ; Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for the CSECT and PSECT, DCB # 
DCB header, POD and RESTBL. 

The POD is expanded by one page by cal- 
ling. Expand with the virtual storage 
address of the POD, the number of pages 
currently in the POD # and a one page expan- 
sion request. 

On return from Expand , the returned vir- 
tual storage address is tested to see if 
the POD was relocated due to expansion. If 
relocated, the POD base and POD pointer in 
the RESTBL have to be updated. An external 
page entry is inserted in the RESTBL Cby 
calling Insert) to correspond to the new 
POD page* Error returns from Insert cause 
an ABEND. The data set length is checked 
to see that the new page added does not 
exceed the maximum allowable size of a par- 
titioned data set. A return code is set if 
the maximum data set length has been 
exceeded. 

The number of POD pages is updated in 
the POD and RESTBL. 

Since the page inserted in the data has 
changed the relative position of all mem- 
bers. Relocate Members CCZC0N) is called to 
update the relative location of existing 
members in the POD* 

Control is returned to the caller by the 
RETURN macro. 



Relocate M embe r s Routin e (CZCON) 

Relocate Members is called by GETNUMBR 
and STOW* to update member descriptors in 
the POD to compensate for added or deleted 
pages within a partitioned data set. Mem- 
ber headers of members that are checked out 
are also updated. CSee Chart PE* ) 

Attributes : Reenterable # read-only # privi- 
leged, public* system. 



Entry Point : 
linkage. 



CZCON1 -- Entered via type-1 



Input : Register 1 contains the address of 
the DCB associated with the data set being 
modified. Relevant fields in the DCB are 
set as follows : 

DCBN Data set page number at which 
relocation must occur- 

DCBM Number of pages inserted or 

deleted. 
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DC BOP '08 00* indicates insert. 



' 0<*00' indicates delete. 



Hodules Called: 



None. 



Ex its : Return to the calling routine. 

Operation : Initialization and general 
register storage is executed in conformance 
with linkage conventions. Base registers 
are declared for the CSECT, DCB f DCB head- 
er, POD, Member Header, and RESTBL. 

Member descriptors in the POD are 
located by searching the hash chains. They 
are examined to determine if they have been 
relocated. The relative location and the 
external page value of the first page of 
each member is recorded in the POD. 

If a member requires relocation (that 
is, it is past the point of relocation), 

the member is tested to determine if it is 
the member causing relocation and if the 
first page is affected. If "the first page 
is affected, the first page value is 

updated and the search of the hash chain is 

continued. 

If the current member is not the member 
causing relocation, or it is the member 
causing relocation and the first page is 
not affected, the POD is updated to reflect 
location. 

The member header chain in the RESTBL is 
searched to determine if the current member 
is checked out Cthat is, active - a member 
header exists). If the member is checked 
out, the member header is updated to 
reflect the relocation. The search of the 
hash chain is resumed. 

When a hash chain is exhausted, the next 
hash chain is searched until all chains 
have been processed. The member header 
chain is tested to see if any members are 

being created. The start of members being 
created is adjusted in the member header 
for any relocation. 

Control is returned to the caller by the 
RETURN macro. 



GETNUMBR Routine CCZCOQ) 

GETNUMBR (Get Member Page Number) is 
called by MOVEPAGE (CZCOC) to convert the 
page number relative to member, to the page 
number relative to the data set; and by 
Insert/Delete Page (CZCOD) to control 
changes in the size of a member. (See 
Chart PF.) 

Attributes : Read-only, reenterable, privi- 
leged, public, system. 



Entry Point : CZCOOl — Via type-1 (privi- 
leged to privileged) linkage. 

Input : Register 1 contains the address of 
the DCB associated with the partitioned 
data set for which memi>er page numbers must 
be corrected. Relevant fields in the DCB 

are: 

DCBN Page number relative to member 
of the first page in the 
request. 

DCBJM Number of pages to be processed. 

DCBOP '8000' - Input. 

•2000' - Output. 

'0800" - Insert. 

•0400' - Delete. 

Modules Called : 

Search (CZCOL1) ■ — Search POD for member 
descriptor. 

Insert (CZCOF1) — Insert pages in RESTBL. 

Relocate Members (CZCON1) — Adjust member 

description for added or deleted pages. 

Reclaim (CZCOG1) — Delete member page 
entries from RESTBL. 

TSEND (CEAH19) -- Wait for shared pages to 
go out of use before deleting pages. 

VDMEP (CZCQK1) -- Output a diagnostic mes- 
sage and terminate the function (but not 
the task) . 

Exits : 

Normal — Register 15 contains one of the 
following return codes: 

■CO* Successful. 

f 04 f No external storage space 
available. 

•08' Storage ration exceeded. 

*0C S No secondary storage allocation 
specified. 

•10' Shared data set RESTBL cannot be 
expanded. 

9 ±U* Maximum data set or member size 
exceeded. 

"18 s Insertion beyond end of data set, 

•1C Deletion beyond end of data set. 

Error -- VDMEP is called if an invalid 

return code is received from Reclaim or 
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Inwert , or it an old member could not be 

located in the POD Cthe member has been 
deleted abnormally) . 

Operat ion: Initialization and general 
registers are stored in conformance with 

linkage conventions. Base registers are 
declared for the CSECT and PSECT, DCB, DCB 
header, member header, POD and RESTBL. 

The offset of the member is tested to 
der..?rjiine if it nas been relocated since 
the last operation. An adjustment has to 

be made in the POD and member header for an 
cid member. Only the member header need be 
adjusted for a new member, since it has not 
been STOWed and no POD entry exists. 

The extent of the current operation is 
tested to see if it is within the range of 
the men\D€:T for a deletion or pure number 
translation, or contiguous to the member 
for an insertion- A return code is set if 
the operation is not within the computed 
limits . 



The page number relative to the member 
is converted to a page number relative to 
the data set. If the operation is not an 
insertion or deletion, control is returned 
to the caller by the RETURN macro. 



If the operation is a deletion, the 

pages are deleted by calling Reclaim 
CCZCOG). If the deleted pages did not 
belong to a member being created but to an 
existing member. Relocate Members CCZCON) 
is called to relocate the member in the POD 
and member headers, by the amount of dele- 
tion. Control is then returned to the 
caller by the RETURN macro* 



Similarly, the data pages are inserted 
by calling Insert CCZCOF) . Relocate Mem- 
bers is called if the insertion was in an 
existing member, to adjust the other mem- 
bers by the amount of the insertion* Con- 
trol is returned to the caller by the 
RETURN macro. 
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PART III 



QUEUED SEQUEOTIAL ACCESS METHOD (QSAM) 



SECTION 1: GENERAL DESCRIPTION 



QSAM routines operate upon data sets of 
queued, sequential organization- They will 
process all of the OS/360 QSAM facilities. 
(QSAM uses move-mode to provide the func- 
tional equivalent for OS/360 substitute- 
mode programs.) In addition, TSS QSAM pro- 
vides the following features not supported 
by OS/360 QSAM: 

1 . Both locate and move mode macro 
instructions can be intermixed on the 
same data set. 

2. Variable record formats are allowed on 
a data set opened for RDBACK. 

3. A SETL routine is provided to alter 
sequential processing of a QSAM data 
set. 

QSAM's basic functions are blocking and 
deblocking logical records, issuing I/O 
requests, checking, and positioning for 
blocks of data. 

QSAM itself blocks, deblocks, and buf- 
fers internally, but uses BSAM to perforin 
I/O operations such as reading, writing, 
checking, and positioning for access to 
data. Through BSAM routines, QSAM also 
provides labeling services and, if 
required, ASCII translation. Table <*9 
lists the modules of BSAM invoked by QSAM, 
and briefly describes their functions. 

QSAM Macro Instructions 



Table 49. Usage of BSAM Modules 

r _ T — T T — 

Title and 

Module ID 1 VCON | RCON | Usage 



READ/WRITE 
CZCRA 

CHECK 
CZCRC 



POINT 
CZCRM 

CNTRL 
CZCRB 

NOTE 
CZCRN 



BSP 
CZCRG 



CZCRAS 



CZCRCS 



CZCRMA 



CZCRBS 



CZCRN A 



CZCRG A 



CZCRAP 



CZCRCP 



CZCRMP 



CZCRBP 



CZCRNP 



CZCRGP 



Reads or writes 
blocks of data 

Checks the com- 
pletion of read 
or write opera- 
tions 

Repositions a 
data set 

Repositions a 
data set 

Returns relative 
address within a 
volume of last 
block read or 
written 

Backspaces a 
data set 



e. The RELSE macro instruction causes 
the remaining logical records in an 
input or update buffer to be 
ignored. 



The macro instructions used on a QSAM 
data set fall into three groups: 

1. Those which are directly serviced by 

QSAM. 



f . The SETL macro instruction speci- 
fies a new start location for 
sequential processing. 



a. The GET macro instruction retrieves 2. 
for the user a single logical 

record. * 

b. The PUT macro instruction adds a 
single logical record to a block of 
records. 

c. The PUTX macro instruction returns 
an updated block of records to a 

data set, or includes a record of 3. 
an input data set in an output data 
set. 



Those which are serviced only by BSAM, 
but affect the operation of QSAM. 

a. The OPEN macro instruction fills in 
certain fields of the data control 
block that were not filled in at 
assembly time, checks volume 
labels, constructs tables, and pro- 
vides work space and buffer areas. 

Those which are serviced mainly by 
BSAM with additional functions per- 
formed by QSAM. 



d. The TRUNC macro instruction causes 
tne next logical record of an out- 
put or update data set to be . 
treated as the first record of the 
next block. 



The CLOSE macro instruction com- 
pletes or purges all outstanding 
I/O requests, releases the storage 
obtained by the OPEN routines, and 
writes trailer labels. 
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irse *:;OJitzi4 program to coioa^ce to 
the n«csstt volume of & dirt^ set; , 

V* * '. - . * A n £ ;-Jt ^ jjk i l'JL ^ Xi^ X £ h t -5 # ,. 

i, ; "v «\ i/i e fc *. O C i ;j w n h OpiOl a .» ; ■:; r. t\ M ( ' lOS .? t O 

* ^ .. £ ■".; ro se^e^cil t.ouu:.-- i <>ub> iut^'/ex';. 1*19 jcqw- 
s j \. i on :^ i wo <. ki. ag s p ^ c c , * \eca ab e .1 1 i 3 

.ii^oi^^;..^. t\o rSYOT, Qo-01 v squires *;•. ^> i.k 
area, s?- & open c^rtdiiiS i h*i S|.;cce for this 
work arBa %*n& also provides buffer areas 

for QSMt 



I. Cue buffer each tor data sets opened 
for Update $ rnd when SETL iS) is 
t r io$ue;st.ec in the T3CB M&CRF fieio 1 - 

f f , Three buffers *o* each dat<* s^t opened 

foi. RDBACK using variable record 
format, 

j. y.v/o buffers each for all othec d&tri 
sets, 

V>SAM*& buffering techuigfueb v,*i.ii be dis - 

massed further in Part II of this section* 



The work area provided for QSAM is known 
as the QWK work &rea e or QWKAR, Hr; 
♦id-lires.? is placed in the DC8QWK field of 
the dai'a control MoiK^ by SAM Open., All 

fie.id.v vithin the QWK work area* except 
those words reserved for data event control 
blacks,, are r&i'~o;red to with a prefix of 
Q Wis. ; , Q WKAR c k m s i s t s o f 1 

1. k l9- uuKd j<jve area {QWKLEN-QWSI3) . 

2 . Siiff icient storage for tirree data 
event con t re i M ock s C DE'CBl - DEC B3 > .. 

io hn S-yord -:>a?e area for sa^imj return 
addresses between subsections of QSAM 



il9.1}^J-Iik^ Blocks 

Following are brief descriptions of enc'r, 
of the control blocks used by QSAM. 



Data Control Block iDCB) t The DCB is 
QSAM's priiiery source of information about 
the data set. It is defined by the user at 
assembly time thxough the DCB macro 
instruction, and niay be filled in or modi- 
fied at. OFRN time or during execution.* 
Appeiidiii 8 contains a list of the ut&in 
fields of the DCB used exclusively by QS&m 
with a brief description of *-.acbu 



% .. kBOthei ^""v»ord h-a^e <>re5 tcr saving 
register contests when EODAD or SYBMj 
is ' invoked JQWKWK1~QWKV»K8> , 

5, Another ll-wcrd save area to/: saving 

r eg i s t e 1 s 5. ft a t y ^e- 2 1 irk -* y ^ . 

The DSSC1 1 used to refer to QWKkR can be 
fooivd in Appendix A. 

In addition to providing the $ra work 
area, S«M Open will, disc provide QSAM witxiz 



Para Kyent. Cont rol Sloc k t OECB) ; The DECE 
provides inf ormatioi? necessary for the ccn- 
tcol of each I/O operation and reflects the 

stittns of the completed operation. QSAM 
i'f.itraiizes the DECB before 3L-''0 requests 

are passed to BSAM1, and the BSAK Posting 
routine completes the control bloclo. 



Data Extemt Block CPEE) : QSAM uses the DEB 
to determine if there are any outstanding,. 

unchecked I/O requests cr error conditions., 



178 °(?®x± III s Queued Sequential Access Method CQSAM> 



SECTION 2: INTERFACE RULES AND MODULE DESCRIPTION 



It is important to note that QSAM is 
designed as a "fence sitter" routine, and 
will run in the same privileged status as 
the routine which invokes it. Also, since 
no linkage is established to the problem 
program when QSAM has been invoked by any 
other routine, all linkage between the pro- 
blem program and QSAM will be of type-1. 

There are 22 subroutines within the QSAM 
module. Since QSAM does not have a PSECT, 
register usage and register saving are kept 
to a minimum by carefully regulating use of 
those registers. 

The linkage between subroutines differs 
from normal linkage procedures, because 
when one subroutine is invoked by another, 
it may not return directly to the invoking 
subroutine without having first invoked one 
or more other subroutines. The normal pro- 
cedures for invoking a subroutine, with the 
return address in register m 9 require a 
separate save area for each of the 22 sub- 
routines, in order to maintain the integri- 
ty of return addresses. The 22 subroutines 
are therefore divided into seven levels, 
such that no subroutine invokes another 
subroutine on the same level, either 
directly or indirectly. For example, the 
GET subroutine on level 3 never invokes 
another subroutine which is also on level 
3, nor invokes any subroutine which in turn 
invokes another subroutine on level 3. 
Thus one register is assigned as a return 
register for all subroutines on one level, 
there being no need for a separate return 
register save area for each level. Thus, 
each subroutine has an exit register based 
upon its level, as defined in the subrou- 
tine interface table (Table 50). 



of any one macro instruction. There is 
also an assigned base reqister foi the 
DECC, known as the DECP.EG, which must be 
loaded by each subroutine using it, since 
there may be more than one DECb in use. 
Registers ana 1 are also reserved to pass 
parameters between subroutines. The para- 
meters expected by each subroutine are 
listed in Table 50. 

Since QSAM generally runs in the same 
privil^qed state as the problem program, it 
may or may not be of the same privilege as 
the BSAM modules which it invokes. All ot 
the modules listed in Table H9, except 
CZCRN, are privileged routines. CZCRN is 
also constructed as a "fence-sitter* rou- 
tine, and will take on the privilege status 
of QSAM whenever it is invoked by QSAM. 
Therefore, type-1 linkage is always estab- 
lished to invoke CZCRN, using the V-con and 
R-con defined within the QSAM module. 

Before establishing linkage to any of 
the other BSAM modules , it is necessary to 
determine the status of QSAM. The subrou- 
tines Read/Write, Check , Point, Control, 
and Backspace perform this function with 
respect to their BSAM counterparts, by 
testing the first bit of the VPSW in the 
ISA table (CHAISA). If QSAM is privileged, 
type-1 linkage is established using the 
V-cons and R-cons defined within the QSAM 
module. If it is not privileged, type-2 
linkage is established via the ENTER SVC, 
with the appropriate code in register 15. 

The parameters expected by the BSAM 
modules and the possible return codes from 
them are listed in Table 51« 



All subroutines are invoked by a BASR 
instruction with register 15 containing the 
entry point address of the subroutine, and 
the exit register of the particular subrou- 
tine containing the return address. The 
invoked subroutine must save its exit 
register in one of the fields (QWKGR1- 
QWKGR7) provided in the QWK work area for 
this purpose, in order that the exit 
register may also be used for calculation 
during processing. When it has completed 
its processing, the subroutine restores its 
exit register and issues a Branch to 
Register instruction (BR) • 

QSAM uses two base registers, which are 
established at each of the nine entry 
points. Another register, the base regist- 
er for the DCB known as DCBREG, is also 
established at each entry point, and 
remains the same throughout the processing 



QSAM Routine CCZCSA) 

QSAM blocks and deblocks logical records 
within a buffer, performs buffering ser- 
vices, and issues requests to BSAM for 
transfer of data between storage and any 
I/O device. (See Chart QA. ) 



Attributes: 



Reentrant, nonrecursive, 



closed, resident in virtual storage, 
assumes privilege of caller. 

Entry Points ; QSAM has nine entry points 
and nine entry sections which serve to 
channel propessing through the appropriate 
subroutines. 

CZCSAA -- Entered upon issuance of the 
first GET on a data set, the first GET 
following a SETL type-E or -B, or the 
first GET following a FEOV. 
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I = us e r wo i k a Lea a cidres s (if a ny ) 
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fl-~Di"b adobes;. 

|0-lnput DCB aodress for output PUTX 

i 

| 1 -DCB address 

I 

j l- : DC£' address 

| 

j i~DCB address 

! 

|0=pointer to TTRZ or ZZCC* 

I 

|1=DCB address 



j i=E>ce address 

i 

S 

j 1=DCB address 

t 

jI-DCB address 

1 

|1=DCB address 

I 

| 1=1X3 address 

1 

|1=DC3 address 

I 

| i=error type code 

|0=DECB address 

1 

fl~BECB address 

I 

| I -DCB address 

| 0=action code and value 

I 

ii=DCB address 

i 

|1=DCB address 

(0=polnter to TTRZ or ZZCC* 

I 

J1=DECB address 

I 

(i==DCB address 



PUT, PUTXIO 



PUTIO 



PUTIO, CHECK, FLUSH ' | 

l 
TREOV, INITIO, GET, CHECK, f 
POINT, BSP, CNTRL j 

I 
BSP, INITIO, GET, SYNAD, CWTRL, | 
TREOV , FLUSH j 

! 

CHECK | 

1 
TREOV, CNTRL, POINT j 

i 

GETIO, READ/WRITE | 

1 
READ/WRITE, CHECK, COMIO | 

READ/WRITE, CHECK, COMIO j 

READ/WRITE, CHECK, GBTIO j 



SYNAD 

SYNAD 

SYNAD 
CHECK 



|*The terms TTRZ and ZZCC refer to the relative form of the retrieval address of any 
I block within a data set on magnetic tape or direct access devices. This address is 
j obtained, in irs relative form, by BSAM NOTE (CZCRN) . TTRZ refers to data sets on 
j magnetic tape, and ZZCC refers to data sets on direct access devices. 
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Table 51. Parameters and Return Codes of 

BSAM Modules 

Table 51. Parameter:; and Return Codes of BSAM Modules 






Parameter v. 



Return Codes 



|CZi"RA |GR1=ULCB address 
ICZCKC |GR1=DECB address 



|GR1 [>cl\ dddrr-'s 
3H0=[.ointer to TTRZ 
or ZZCC 



|GR1^DCB address 
(LR0 = action code and 
number value 

ICZCRG |GR1=DCB addresj 



ICZCRN |GR1=DCB addresj 



| None 

JYKAD request flag in DECB 
fLuDAD flag in DCB 
|GK0=DECB address 

(Normal return, GR15=0 
| Error return, GR15-U 
| Unrecoveraole error flag 
|in DLB 

| Normal return, GR1S=G 
| Error return, GR15#0 



j Normal return, GR15=0 
| Error return, GR1S*Q 

|GR1=TTRZ or ZZCC address 



CZCSAB — Entered upon issuance of the 

first PUT on a data set, the first PUT 
following a SETL type-E or -B, or the 
first PUT following a FBOV. 

CZCSAG — Entered upon issuance of all GETS 
except those listed under CZCSAA. 

CZCSAW — Entered upon issuance of all PUTs 
except those listed under CZCSAB. 

CZCSAX — Entered upon issuance of a PUTX. 

CZCSAT — Entered upon issuance of a TRUNC. 
CZCSAR — Entered upon issuance of a RELSE. 

CZCSAV — Entered only by SAM Close or 

FEOV. 

CZCSAS — Entered upon issuance of a SETL. 



Input : The following parameters are 

passed: 

Register — Address of work area (if any) 
for entries CZCSAA f CZCSAB, CZCSAG, and 
CZCSAW. 

Register — Address of input DCB for 
CZCSAX when an output-mode PUTX is 
issued. 

Register 1 -- Address of DCB for all entry 

points. 

Data References : CHADCB, CHADEC, CHADEB, 
CHAI5A, QWKAR. 

Modules Called : 

BSAM Read/Write (CZCRA) — Entry at CZCRAS. 
For data transfer. 

BSAM Check (CZCRC) — Entry at CZCRCS. 
Test I/O results. 



BSAM Point (CZCRM) — Entry at CZCRMA. 
Reposition a data set. 

BSAM Control (CZCRB) -- Entry at CZCRBS. 
Reposition a data set. 

BSAM Backspace (CZCRG) — Entry at CZCRGA. 
Backspace. 

BSAM Note CCZCRN) ~ Entry at CZCRNA. 
Identify last record read or written. 



Exits ; 
Normal 



Return to the calling routine. 



Error -- ABEND termination under the fol- 
lowing conditions: 

a. During processing of a GET macro 
instruction, when the computed sum of 
the logical record lengths (11) of 
variable length records does not 
equal the specified block size CLL) . 

b. During processing of a PUT macro 
instruction, when the user attempts 
to PUT a logical record longer than 
the specified maximum block size. 

c. During processing of a PUT macro 
instruction, when the user specifies 
a value in the length control bytes 
(11) of a variable record larger than 
the logical record length previously 
estimated in the DCB. 

d. During processing of a PUTX macro 
instruction, when the previous macro 
instruction was not a locate-mode 

GET. 

e. During processing of an output-mode 
PUTX macro instruction, issued on an 
output DCB whose address is in 
register 1, when the associated DCB f 
whose address is in register ( has 
been opened for Output. 

f . During construction of a block of 
fixed format records, if the user 
causes an incorrect length output 
block to be created by changing the 
value of the logical record length. 

g. When a PUT macro instruction is 
issued on an update, input, or read- 
back data set, or when a GET macro 
instruction is issued on an output 
data set. 

h. When a SETL is issued, but there is 
no (S) in the DCB MACRF. 

Otherwise, exit to user's SYNAD or EODAD 
routine. 

Operation : The subroutine functions are 
shown in Table 52. 
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Table S2. Subroutine Function? 



j Name i 

k— — ~-H 

[GET 


Entry (s) \ Chart! 
>„__„„„ .„ + - H 

CZCAS7 S DM 


Function 

Deblocks logical records 


| PUT 


CZCSA8 






ON 


Blocks logical records 


|PUTX 


C2CSA2 






DO 


Returns logical records retrieved by a locate-mode 
GET to an UPDATE or OUTPUT data set 


jTRUNC 


CZCSA3 






DP 


Truncates current block (output or update) 


jRELSE 


CZCSA4 






DQ 


Releases current block (input, update, or readback) 


jTREOV ! 


CZCSA9 






DR 


Completes or purges outstanding I/O requests 


fSETLR 


CZCSAi 






DS 


Positions data set at specified retrieval address 


jSETLP 








DT 


Positions data set at previous logical record 


1SETLC 


CZCSAZ 






DU 


Obtains retrieval address (TTRZ or ZZCC) of current 

logical record 


| SETLEB 


CZCSAH 






DV 


Positions data set at beginning or end of current 
volume 


| INITIO 


CZCSA6 






DW 


Initializes buffer addresses f block size # etc. , and 
constructs DECBs 


|GETIO 


CZCSA5 
(Entry 


from 


GET) j 




Performs buffering for input operations 




CZCSAI 
(Entry 


from 


PUTX) 1 






|PUTIO ' 


CZCSAU 








| Performs buffering for output operations 


(PUTXIO 


CZCSAJ 








Performs buffering for update data sets 


|COMIO 


CZCSAM 






DX 


| Initializes for a new buffer 


| SYNAD 


.CZCSAN 








(Transfers control to user's SYNAD routine and 
performs checks on error options 


| READ/WRITE 


CZCSAD 
(Entry 


from 


GETIO) | 




Issues an I/O request for data transfer 




CZCSAE 
(Entry 


from 


PUTIO) | 






|CNTRL 


CZCSAC 








Requests repositioning of data set 


)BSP 


CZCSAY 








Requests backspacing of one block 


[POINT 


CZCSAP 








Requests repositioning of data set 


(CHECK 


CZCSAK 








Requests a check on results of an I/O operation 


(FLUSH 


CZCSAF 








Purges I/O activity from DECB queue 



-, J. . — 



J JL . . . . . . J 
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Blocking Logical Records : The user 
issues a PUT macro instruction for each 
logical record he wishes to include in 
the output data set. The PUT subroutine 
adds the logical record to the block if 
it will fit within the current buffer. 
Otherwise, tne block is considered com- 
plete, and the record for which the PUT 
was issued will be treated as the first 
record of a new block. The user can 
cause a block to be regarded as complete 
prematurely by issuing a TRUNC macro 
instruction. 



Deblocking Logical Records ; The GET 
subroutine returns to the user a single 
logical record each time he issues a GET 
macro instruction. When a block of 
records has been read and checked, the 
buffer address of the first logical 
record is returned to the user if the 
GET macro instruction was in locate 
mode,* or, if it was in move mode, the 
first logical record is moved to his 
work area. When the current block is 
completely processed, the next GET 
issued causes the buffer to either be 
refilled if the data set was opened for 
Input or Rdback, or to be written back, 
if required, to an update data set and 
then refilled. At any time, the user 
can cause processing on a buffer to be 
regarded as complete by issuing a RELSE 
macro instruction. 

Buffering Blocks of Data : The normal 
buffering facility of QSAM is known as 
double buffering. This involves the use 
of two buffers, one of which will be 
currently in use while I/O activity is 
being performed on the other. Thus, on 
a normal input or readback data set, 
while logical records from one buffer 
are being supplied to the user, the 
other buffer is being refilled. On a 
normal output data set, QSAM will con- 
tinue adding logical records to one 
buffer while the other is being written 
out. 



Once a buffer has been either filled or 
written out, and checked, it is available 
for processing, and QSAM will begin return- 
ing logical records from it to the user, or 
adding logical records to it as they are 
supplied by the user. When this current 
buffer is completely processed, QSAM issues 
either a rt»ad request to refill it, 01 a 
write request to wri * t- it ou 4 . Ther the 
previous read or write operation is 
checked, and that buffer becomes available 
for processing. Bufferinq is performed for 
input or readback, output, and update data 
sets by the GETIO, PUTIO, ana PUTXIO sub- 
routines, respectively. 

Under some circumstances, it is neces- 
sary to perform only single buffering; that 
ii , only one buffer is used. In this case, 
the pointers to th^ two DECBs are both set 
to point to the first DECB, so all opera- 
tions will be performed on the same DECB 
regardless of the switching of pointers. 

The decision to use double or single 
buffering is based on the OPEN option of 
the data set, or on the combination of 
device type and macro option specified in 
the DCB. Double buffering will be done ii 
all cases except the following: 

1. When the data set- is opened for 
UPDATE. 

2. When the DCB MACRF requests a SETL 
(S) . 

Single buffering must be done on an up- 
date data set to allow the user to update 
one block of records at a time. No reading 
ahead can be done until it is determined 
whether or not the current block of recoris 
must be updated, since an update write can 
only return the last block read. 

With double- but tering facilities, QSAM 
requests two writes before requesting a 
check on the first write. 

Examples of Double Buffering: 



Each buffer is assigned to one of the 
first two DECBs contained in QSAM's QWK 
work area. Pointers to these DECBs are 
contained in the DCB ( DCBDE1 and DCBDE2) . 
To achieve the alternating of buffers, all 
read or write operations are performed on 
the DECB pointed to by DCBDE2, and all 
checking operations are performed on the 
DECB pointed to by DCBDE1 . Following each 
checking operation, the two pointers are 
switched so that, when the next I/O is 
initiated, the read or write performed on 
the DECB previously pointed to by DCBDE2 
and now pointed to by DCBDE1 will be 
checked, and the buffer belonging to the 
DECB now pointed to by DCBDE2 will be eith- 
er refilled or written out. 



I. Double buffering involvina an output 

data set. 



Phdse I 

DCBDE1 

I 
V 

DECB1 

I 

V 
Buffer I (empty) 



DCBDE2 

I 
V 

DECB 2 

I 
V 

"uffer II (available 

for processing) 



QSAM builds the first block of the 
user's data set in Buffer II by adding to 
the buffer each logical record for which a 
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POT is issued, until the buffer is full. 
Then a write request is issued for Buffer 

II, a check request is issued on Buffer I 
fsince DECB1 is initialized by QSAM to in- 
dicate normal completion, this check con- 
stitutes a dummy request) f and the DECB 
pointers are switched. 

Phase II 



primed, an initial read is requested on 
Buffer 1. (This varies from the normal 
procedure of requesting reads only on the 
DECB pointed to by DCBDE2.) Then another 
read is requested to fill Buffer II, a 
check is requested on Buffer I r and the 
DECB pointers are switched. 

Phase II 



DCBDE2 

I 
V 

DECB1 



Buffer I Cavailable 
for processing) 



DCBDE1 

I 
V 

DECB2 

I 

V 
Buffer II (written 
out, unchecked) 



QSAM now builds the second block of 
records in Buffer I. When it is complete, 
a write request is issued for Buffer I, a 
check request is issued for Buffer II, and 
the DECB pointers are switched* 



Phase III 



DCBDE1 

I 

V 
DECB1 



Buffer 1 (written 
out, unchecked) 



DCBDE2 

I 
V 

DECB2 



Buffer II I written 
out* checked, now 
available for 
processing) 



Buffer II is again available for proces- 
sing. The third block of the data set is 
built in Buffer II, and when complete, a 
write request is issued for Buffer II, a 
check request is issued for Buffer I, and 
the DECB pointers are again switched- Thus 
the processing operation continues, alter- 
nating the buffers used, until the user has 
placed the last logical record of his data 
set in the buffer, at which time he may 
CUOSE the data set, causing the last block 
of records to be written out and checked 
immediately* 

II. Double buffering involving an input 
data set. 



Phase I 



DCBDE1 

i 
v 

DECBl 



Buffer I Cread, 
unchecked) 



DCBDE2 

1 

V 
DECB2 



Buffer II fempty) 



DCBDE2 

I 
V 

DECBl 

I 

V 
Buffer 1 Cread, 
checked, and avail- 
able for processing) 



DCBDE1 

i 
V 

DECB2 

I 
V 

Buffer II Cread, 

unchecked) 



Each of the logical records in Buffer I 
is returned to the user when he issues a 
GET macro instruction. When all the reco- 
rds in Buffer I have been returned to him, 
a read request is issued to refill Buffer 
I, a check request is issued on Buffer II, 
and the DECB pointers are switched. 



Phase III 



DCBDE1 

I 
V 

DECBl 



Buffer I Cread, 
unchecked) 



DCBDE2 

I 
V 

DECB2 



Buffer II Cread, 
checked, and avail- 
able for processing) 



Since on the first I/O request of an 
input data set, both buffers must be 



Buffer II is now the current buffer in 
use, and each of the logical records in it 
is returned to the user until there are 
none left, at which point Buffer II will be 
refilled, Buffer I will be checked, and the 
DECB pointers will be switched again. Pro- 
cessing continues in this manner until an 
end of data set is encountered. At that 
point, the user's EODAD routine gains 
control . 

III. Double buffering on a readback 
data set. 

Double buffering on a readback data set 
of fixed or undefined length records is 
handled in the same manner as that on an 
input data set, except that blocks of reco- 
rds are read beginning with the last block 
of the data set. However, if a data set 
opened for Rdback specifies variable- format 
records, the procedure is varied to t include 
the use of a third buffer. After a block 
of records has been read and checked, a 
copy of it is moved to the third buffer. 
This copy is used as a table to contain 
record lengths so that the records con- 
tained in the actual buffer may be accessed 
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in reverse order. A t orwa rd search is made 
through the block for the length control 
oytes (11) in front of each record, and 
these bytes are saved in the blank control 
bytes Cbb) of the following record- The 
length of the last record in the block is 
saved in the DCB in order that the address 
of the first record to be accessed C logic- 
al iy the last record of the block) may be 
computed. The following diagram demon- 
strates the layout of the third buffer. 



LLBB 



ll.bb DATA 



11,11, DATA 11,11, DATA 



x: 



xz 



xz 



il 3 -DCBSVL 



The beginning-of-buf f er address for 
blocks of records in a readback data set is 
at the logical end of the block. By sub- 



tracting from th.it address the length of 
the last record in the block, which is 
saved in the DCB r the first record 
requested by the user is accessed from the 
actual buffer. Then the length of the pre- 
ceding record is obtained from the control 
bytes of the current record in the third 
buffer, and saved in the DCB so that the 
address of the next record may be computed. 
By maintaining its own copy of the current 
buffer, QSAM can be certain the lengths of 
the previous logical records recorded in 
the control bytes are always correct. 



Issuing I/O Requests, Checking, and Posi- 
tioning for Blocks of Data : QSAMs internal 
functions are performed entirely within 
storage. Any I/O requests for transfer of 
data between storage and any I/O device, or 
requests for repositioning a data set, are 
passed on to BSAM. Table 50 in this sec- 
tion lists the BSAM modules invoked by QSAM 
and the expected return codes. 
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Before discussing the internal logic of 

the QS AM routine in relation to QSAM macro 

instructions, it is necessary to establish 
certain rules which will be followed throu- 
ghout the discussion. 

1. All fields within the DCB f when 
referenced, have a prefix of DCB« 

;. Ail fields within the DECB, when 
referenced, have a prefix of DEC* 

3. All references to fields within either 
table indicate the contents of the 
field unless it is specifically stated 
otherwise. 



exit is required, the appropriate flags are 
set in the DCB f and a return is made to the 
calling subroutine. 



Read/Write Subroutine 

The Read/Write subroutine has two 
entries. * CZCSAD is the entry when a read 

request is issued, and CZCSAE is the entiy 
when a write request is issued. The appro- 
priate type, code is set into the DECB, and 
linkage is established to BSAM Read/Write, 
When control is returned to Read/Write , a 
return is made to the calling subroutine* 



4. Each of the nine entry subroutines is 
referred to by the name of its entry 
point. A calling module always enters 
QSAM at the entry point itself. For 
internal processing, however , a 
reference to "returning to CZCSAA" 
will indicate the entry subroutine* 
not the entry point. 

5. Since certain of the QSAM subroutines 
have the same names as BSAM modules, 
such as Read/Write or check, reference 
to the BSAM module of that name will 
always be clearly marked by referring 
to "BSAM Read/Write CCZCRA) ■ or by 
using just the module ID "CZCRA* after 
it has been identified with the name 
of the module. 



COMMON PROCESSING 

Certain of the QSAM subroutines perform 
the same function each time they are 
entered, regardless of the type of data 
set, device or macro instruction being 
used. To simplify the tracing of each 
macro instruction, these subroutines are 
briefly described below, and thereafter 
referred to only to indicate the specific 
points at which they are invoked to perform 
their functions* 

S YNAD Subroutine 

SYNAD is entered whenever an error in 
reading, writing, or positioning has 
occurred. If the user has provided his own 
SYNAD routine, a copy of the DECB on which 
the error occurred is moved to DECB3, and 
control is passed to his SYNAD, If not, or 
upon return from the user's SYNAD, tests 
are made to see if the erroneous block may 
be accepted or skipped, or if the task must 
be abnormally terminated. If no abnormal 



Control Subroutine 

The Control (CNTRL) subroutine invokes 
the BSAM Control routine. If the return 

code from BSAJM Control is not zero, the 

SYNAD subroutine is invoked* Otherwise, a 
return is made to the calling subroutine. 

Backspace Subroutine 

The Backspace subroutine invokes BSAM 
Backspace* After control is returned to 
Backspace, a return is made to the calling 
subroutine* 

P o i n t s u brou t i n e 

The Point subroutine invokes BSAM Point, 
On return from CZCRM # the SYNAD subroutine 
is invoked if the return code register con- 
tains a four. If the return code is zero, 
or upon return from SYNAD, a return is made 
to the calling subroutine. 

Check Subroutine 

The Check subroutine establishes linkage 
to BSAM Check (CZCRCK After control is 
passed back from CZCRC, if SYNAD is 
requested the SYNAD subroutine is invoked, 
and after control is passed back to Check f 
a return is made to the calling subroutine. 
If SYNAD is not requested and EODAD is 
indicated, control is passed to the user's 
EODAD routine, from which no return is 
expected. Otherwise, a return is made to 
the calling subroutine. 

Flush Subroutine 

Three cases exist: 

1. If no 1/0 requests are outstanding, an 
exit is made to the calling 
subroutine. 
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2. When any I/O request is outstanding 
and the DECS has been marked inter- 
cepted and EODAD has been requested, 
then the number of outstanding I/O 
requests in the DEB (DEBNCP) is set to 
zero, and a return is made to the cal- 
ling subroutine. 

3, If the I/O request which remains out- 
standing is not complete, an AWAIT SVC 
is issued and the completion is 
awaited. The Purge flag in the DECB 
is then set on, and control is passed 
to the Check subroutine. Upon return 
from Check, a return is made to the 
calling subroutine. 

GETIQ Subroutine 

The GETIO subroutine first invokes Read/ 
Write to perform a read on the DECB pointed 
to by DCBDE2, and then invokes Check to 
check the read done previously on the DECB 
pointed to by DCBDE1. If Check detected an 
error in the read operation and the user 
indicates it is to be skipped, GETIO 
switches the DECB pointers and goes back to 
repeat the reading and checking operations, 
until no error is detected. Otherwise, 
GETIO invokes the COMIO subroutine to 
initialize buffer addresses, and then 
returns to the calling subroutine. 

PUTIQ Subroutine 

PUTIO invokes Read/Write to perform a 
write on the DECB pointed to by DCBDE2, and 
then invokes Check to check the DECB 
pointed to by DCBDE1. PUTIO gives control 
to COMIO to reinitialize the free buffer, 
and then makes a return to the calling 
subroutine, 

PUTXIO Subroutine 

IF A PUTX has been issued on the current 
block, PUTXIO invokes Read/Write to write 
the updated block back to the data set, and 
Check to check the completion of the write. 
Following this, or if no PUTX was issued on 
the block, PUTXIO invokes GETIO to read and 
check the next block. It then returns to 
the calling subroutine. 



LOGIC OF MACRO SERVICES 

The logic of the GET, PUT, and PUTX 
macro instructions can be broken down into 
three phases. Phase 1 deals with the com- 
munication between the problem program and 
the body of the QSAM routine. Phase 2 
describes the initialization which is done 
only for: the first of these macro 
instructions issued on a data set; the 
first issued after a SETL type-E or -B has 
repositioned the data set; or the first 
after FEOV has advanced to a new volume in 



the data set. Phase 3 will describe the 
functions performed for all the above macro 
instructions when subsequently issued. 



GET Macro Processing 



Phase 1 - Communication : When the user 
issues a GET macro instruction, the macro 
expansion sets a locate or move mode code 
in the DCB, and then establishes type-1 
linkage to the QSAM entry point whose V-con 
is found in DCBGTV. At the entry point, 
the user's registers are saved, and base 
registers for QSAM are established. If 
CZCSAA is entered, phase 2 is begun by giv- 
ing control to INITIO. If CZCSAG is 
entered, phase 3 is begun by giving control 
to GET. 



Phase 2 - First GET; Initialization : 
INITIO fills in two DECBs, for all data 
sets, and places their addresses in the 
DCB. It sets the forward or backward reads 
byte in the DECB, and sets the addresses of 
the buffers obtained by SAM Open into the 
data area pointers of the DECBs. Then the 
DCB address and the maximum block size are 
set into the DECBs. If single buffering is 
being done, the DECB pointers in the DCB 
are set equal to each other, and GETIO is 
invoked to read and check the first block. 
If double buffering is being done, Read/ 
Write is invoked to read the first block, 
and GETIO is then invoked to read the 
second and check the read of the first. 

Before returning to INITIO, GETIO gives 
control to COMIO to initialize buffer 
addresses. COMIO calculates the actual 
size of the block read in, by subtracting 
the residual count in the CSW from the 
naximum block size. It sets the current 
record address in the DCB from the data 
area address in the DECB, and then calcu- 
lates the end-of-buf f er address using the 
actual block size. If the record format is 
variable, four is added to the record 
address to allow for the four system con- 
trol bytes in front of the block, and the 
sum of the lengths of the records is 
checked against the block size. If they 
are not equal, and if the user had not 
specified an ERGPT parameter of ACC in the 
DCB, the task abnormally terminates by 
executing an ABEND macro instruction. 
Otherwise, COMIO returns to GETIO, which 
immediately returns to INITIO. Before 
returning to CZCSAA, INITIO places the 
V-con of CZCSAG in DCBGTV and DCBGTR, in 
order that the next GET issued by the user 
will enter QSAM at that point. 

After INITIO has returned control to 
CZCSAA, the Get subroutine is invoked, and 
phase 3 is entered. 
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*iL : f:i?>; ' - Cyc xation: If processing on the 
current: buffer is complete. Get invokes 
(■ither PUTXIO, to write an updated block 
back to an update data set, and read in the 

next block, or it invokes GET 10 to refill 
t h * • co in [ > 1 e t e d ou ifez. After t he re t urn 
t i cm f ither PUTXIO or GETIO r or if proces- 
;;.mu on the current Duffer is not yet com- 

t Lett', GET calculates the current record 
address, and if the GET macro instruction 
was in locate mode, sets the current record 
address into register 1 in the user's save 
area. If the GET macro instruction was in 
move mode, the record is moved into the 
user's work area. 

Then the record address is incremented, 
Lj tne length of the current logical reco- 
rd, so as to point to the end of the reco- 
rd. If it is within the block, an immedi- 
ate return is made to the entry section. 
It it is at the end of the block, a flag in 
x.hf- rCB ±s set on to indicate that proces- 
jij^I on the current buffer is complete, and 
the return is made. If it lies outside the 
block, and if the user has not specified an 
LROPT parameter of ACC in the DCB r the task 
abnormally terminates by executing an ABEND 
macro instruction. Otherwise, the return 
to the entry section is made. 

Since processing on any GET macro 
instruction is now complete, both CZCSAA 
and CZCSAG issue a RETURN macro instruc- 
tion, to restore the user's registers, and 

link back to the problem program. 



>UT Macro Processing 



Phase 1 



Communication; 



When the user 



issues a PUT macro instruction, the macro 

expansion indicates either locate or move 
mode in the DCB, and establishes type-1 
linkage to the QSAM entry point whose V-con 
is in DCBPTV. At the entry point, the 
user's registers are saved , and base regis- 
ters for QSAM are established. If CZCSAB 
is entered, phase 2 is begun by giving con- 
trol to INITIO. If CZCSAW is entered, 
phase 3 is begun by giving control to PUT. 

Phase 2 - First PUT - Initialization : 
INITIO builds two DECBs for all output data 
sets, as described in phase 2 of the GET 
macro instruction , except that it sets the 
DECB type code to indicate that only writes 
are to be done* It then invokes the BSAM 
Note routine (CZCRN) to obtain the relative 
address within the volume CTTRZ or ZZCC) of 
the last block read or written. If single 
buffering is being done, the DECB pointers 
in the DCB are set equal to each other. If 
double buffering is being done, the comple- 
tion code in the DECB is set to indicate 
"complete with no errors" , so that the 
first check, which will be done on an 
unused DECB, will return normally. Follow- 
ing this, if the record format is variable. 



tne two length control bytes at the begin- 
ning of the block are initially set to 
four, and the current logical recora 
address is set to the beqinning-of -buf f er 
address, plus four. The end-of-buf f er 
address is calculated by adding the maximum 
block size to the beginning-of-buf f er 
address. 

The V-con of CZCSAW is placed in DCBPTV 
so that the next PUT issued will enter QSAM 
at that point, and a return is made to 
CZCSAB. From CZCSAB, control is then 
passed to Put, and phase 3 is entered, 

Pnase 3 - Operation : If the current block 
of records is complete. Put gives control 
to PUTIO to write the block out and check 
the previous write operation. The record 
format is checked, since variable format 
records are treated separately from fixed 
and undefined, the end~of~-buf f er address is 
set to the current record address plus the 
logical record length. Then, for both 
fixed and undefined records, if the PUT 
macro instruction is in locate mode, the 
current record address is set into register 
1 in the user's save area. If the PUT is 
in. move mode, the record is moved from the 
user's work area to the current record 
address, and in order to support substitute 
mode exchange buffering, the address of the 
user's work area is set into register 1 in 
his register save area. 

If the block is complete, the End of 
Buffer flag in the DCB is set on. If the 

block is not yet. complete, or after the End 
of Buffer flag is set, the logical record 
count for the current block is increased by 
one, and a return is made to the entry sec- 
tion. If the record overflowed the buffer, 
the task abnormally terminates by executing 
an ABEND macro instruction. 

For variable format records, a check is 
first made to see if the last PUT issued 
was in locate mode. If so, the length con- 
trol bytes of the record which was subse- 
quently built in the buffer are checked to 
be sure that the record is not larger than 
the length previously estimated by the 
user. If it is larger, and if the record 
is too long to fit into the buffer # the 
task is abnormally terminated. 

Following this, or if the last PUT was 
not in locate mode, if the current record 
will not fit into the buffer, PUTIO is 
invoked to write out the buffer, check the 
previous write, and provide a new buffer 
address. After return from PUTIO, or if 
the current record will fit into the buff- 
er, the current record address is set into 
register 1 of the user's register save area 
if the PUT is in locate mode , and a return 
is made to the entry section. If the PUT 
is in move mode, the record is moved from 
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the user's work area to the current record 
address, which is then incremented by the 
length of the record. 

Since processing on any PUT macro 
instruction is then complete, both CZCSAB 
and CZCSAQ issue a RETURN macro instruction 
to restore the user's registers and return 
to the problem program. 

PUTX Macro Processing 

Phase 1 - Communication : When a PUTX macro 
instruction is issued, the macro expansion 
establishes type-1 linkage to CZCSAX, whose 
V-con is in DCBPXV. At the entry point, 
the user's registers are saved, and base 
registers for QSAM are established. If the 
PUTX is an update PUTX, it must have been 
preceded by a locate mode GET on the same 
data set, and therefore cannot be the first 
macro issued. Hence, phase 3 is begun by 
giving control to the PUTX subroutine. If 
it is an output PUTX, a check is made to 
see if it is the first macro issued on the 
data set, and if so, phase 2 is begun by 
giving control to INITIO. Otherwise, PUTX 
is invoked. 

Phase 2 - First PUTX - Initialization : The 
initialization for the first PUTX on a data 
set is accomplished by INITIO in exactly 
the same manner as that for the first PUT 
on a data set. When initialization is com- 
plete, a return is made to CZCSAX, which 
then gives control to PUTX. 

Phase 3 - Operation : If the data set on 
which the PUTX macro instruction was issued 
is opened for Output, the associated data 
set must be opened for Output, and if it is 
the task abnormally terminates by executing 
an ABEND macro instruction. The record 
which is to be put out must have been 
retrieved by a locate-raode GET on the asso- 
ciated data set. If it was not, the task 
is abnormally terminated. Otherwise, a 
flag is set in the output DCB to indicate 
that a move-mode PUT is to be performed, 
the logical address field of the input DCB 
is supplied as the address of the record to 
be output, and control is given to the PUT 
subroutine (whose operation was discussed 
in phase 3 of the PUT macro instruction) . 

The data set must be opened for Output 
and Update, and the last logical record 
must have been retrieved by a locate mode 
GET; otherwise, abnormal termination 
occurs. 

A flag is set in the DCB to indicate 
that a PUTX has been issued on the current 
block. If processing on the current block 
is complete, PUTXIO is invoked to write the 
updated block back to the data set, and to 
read in the next block if called by the GET 
subroutine. After the return from PUTXIO, 



or if processing on the block was not com- 
plete, a return is made to CZCSAX, which 
then issues a RETURN macro instruction to 
restore the user's registers and link back 
to the problem program. 

TRUNC Macro Processing 

The macro instructions TRUNC and RELSE 
require no initialization phase, since they 
perform no functions if they are the first 
macro instructions issued on a data set. 
Therefore, they will be discussed in only 
two phases, communication and operation. 

Phase - Communication : The expansion of 
the TRUNC macro instruction establishes 
type-1 linkage to CZCSAT, whose V-con is 
defined within the expansion. The entry 
section saves the user's registers, estab- 
lishes base registers for QSAM, and gives 
control to the TRUNC subroutine. 

Phase 2 - Operation : TRUNC makes an imme- 
diate return to the entry section under the 
following conditions: 

1. If processing on the current block is 
already complete, or has not yet 
begun; 

2. If the record format is undefined; 

3. If the data set is opened for neither 
Output nor Update; 

4. If no GET or PUT has previously been 
issued on the data set. 

Otherwise, if the data set is opened for 
UPDATE, TRUNC sets the End of Buffer flag 
in the DCB so that the next GET will retri- 
eve the first logical record of the follow- 
ing block. If the data set is opened for 
Output, and if the record format is vari- 
able, and if the last PUT was in locate 
mode, the last logical record is checked to 
be certain it does not overflow the buffer. 
If it does, the task is abnormally ter- 
minated. In all other cases, the actual 
block size is calculated, and PUTIO is 
invoked to write out the block. 

RELSE Macro Processing 

Phase 1 - Communication : The expansion of 
the RELSE macro instruction establishes 
type-1 linkage to CZCSAR, whose V-con is 
defined within the expansion. The entry 
section saves the user's registers, estab- 
lishes base registers for QSAM, and gives 
control to the RELSE subroutine. 

Phase 2 - Operation : RELSE makes an imme- 
diate return to the entry section if pro- 
cessing has not yet begun on the current 
block, or if the data set is opened for 
Output. Otherwise, it sets the End of 
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ui"j t h <c d.-< * a s e? will r et r i ev e r h e i" i *. s t 
i.^icdi record oi the following block. 

Thei\ RELSE returns to CZCSAB, which issues 
a RETURN macro instruction to restore the 

user's-; registers and link back to the pro- 
blem program* 
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communication phase is the same for 
pas of SETL macro instructions, but 

era t ion phases must be discussed 
tely. The expansion of each SETL 
instruction sets a code in the DCB to 
te its type (C, R, P, E or B) , and 
ishes type-1 linkage to CZCSAS, whose 
is found in DCBSLV. The entry sec- 
aves the user's registers and estab- 

base registers for QSAW. It then 
control to SETLC, SETLR, SETLP, or 

The routine ABENDS if SETL was not 
ted in the DCB MACRF- Single buffer- 
done for SETL. 



(Current Block): The SETLC 



subroutine first: invokes CHECK to check the 
last read or write performed, and then 

gives control to BSAM Note CCZCRN) to esta- 
blish the relative address CTTRZ or ZZCC) 
wdrnla the data set of the last block read 
oi wri.reiu .Since that may not be the 
block currently being processed, it must be 
determined whether or not additional spac- 
ing will be needed. The data set is re po- 
sit i on ed to t h at retri eva 1 a ddr es s . 

If the data set is opened for Output, 
aim . £ it is not positioned to the begin- 
ning, 1 is coded to toe retrieval address, 
since the cur' rent block will always be 1 
beyond the last block written. The count 
of logical records already processed within 
the current block is then returned to the 
user, along with the retrieval address. 

If the data set is opened for Update , a 
test roust be i&ade to see if the current 
record address points to the beginning of 
the- block- This is possible only when a 
PTJTX macro instruction, issued on the last 
record of a block, has caused thar block to 
be written back to the data set and a new 
oi o ck to oe r ea d in- in this case, a ba c k~ 
space will re required to retrieve the 
block within which the desired record 
resides- Therefore , the count of records 
within the last block , with the high order 
bit set on to indicate that a backspace is 
needed, is returned to the user with the 
retrieval address. If the current record 
address points within the block, no back- 
space is needed, since a GET must already 
have been issued on the block. Hence, the 
count of records already processed within 
the current block is returned to the user 
with the retrieval address. 



fli.ace a datd set opere-u ior Input or 
RDBACK employs double buffering, o:.v d... ,> 
beyond the current one being processed win 
be the one marked by CZCRN. Therefore, 
either a backspace or a forward space will 
always be required to ret ii eve t hr oiKit-ut 
block. The count ot records processed 
within the current block (with the nigh on - 
der bit set on to indicate that a backward 
or forward space is needed) is returned to 
the user with the relative address obtained 
by CZCRN. 

When processing is complete, a retain is 
made to CZCSAS, which then issues a RETURN 
macro instruction to restore the user's 
registers and link back to the problem 

prog ram . 

SETL Type-R (Retrieval Address ) : The SETLR 
subroutine first invokes TREOV to clear any 
outstanding I/O requests. Then, using the 
retrieval address provided by the user as a 
parameter, the SETLR subroutine invokes 
POINT to reposition the data set to the 
block specified by the retrieval address. 
If a backward or forward space is required 
Csee SETL type-C for the manner in which 
this is determined) , either Backspace is 
invoked to backspace one block, or Control 
is invoked to forward space one block. 

Following this, the original open opt. i on 
is saved, and if the data set is opened for 
Output, the open option is set to indicate 
that the block to which tne data set is now 
positioned must be read back in. INITIO is 
invoked to set up new DECBs and initiate a 
read of the desired block* INITIO will 
function as it does in phase 2 of the GET 
macro instruction, except in the case of an 
output data set, when it sets the DECB type 
code to "read* and invokes Read/Write to 
read in the desired block and GETIO to 
check it . 

When INITIO returns control to SETLR, 
the current record address points to the 
first record of the block. The record 
count provided by the user is then 
decreased by one, and if the result is not 
zero, the Get subroutine is invoked to cal- 
culate the address of the next logical 
record. Again the record count is 
decreased by one, and GET is invoked if it 
is not zero* When the record count reaches 
zero, the current record address points to 
the desired record. At this point, the 
original open option is restored, and # if 
the data set is opened for Output , tht- DECB 
type code is reset to "write". A return is 
made to CZCSAS, which issues a RETURN macro 
instruction to restore the user's registers 
and link back to the problem program, 

SETL Type~P (Previous Record) : The SETLP 
subroutine first checks to see if proces- 
sing has begun on the current buffer. If 
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so, the previous record must be within the 
current block. Its address is calculated, 
the record count within the block is 
decreased by 1, and a return is made to 

CZCSAS. 



If the current buffer is empty, however, 
:he previous record lies within the last 
olock processed. In this case, TREOV is 
invoked to clear any outstanding I/O 
requests. Upon return from TREOV, if the 
Write Request flag in the DCB is on, an 
immediate backspace of one block is made. 
If the data set is opened for RDBACK, Con- 
trol is invoked to space forward one block. 
If the data set is opened for Input, Check 
is invoked to check the last read and then 
Backspace is invoiced to backspace the data 
set three times, since it is positioned at 
the end of the third block beyond the one 
in which the desired record lies. If the 
data set is opened for Output, it is posi- 
tioned at the end of the block containing 
the desired record, and BSP is therefore 
invoked to backspace one block. If any 
positioning errors occur, SYNAD is invoked. 

When the data set is correctly posi- 
tioned, the open option is saved, and if 
the data set is opened for Output, the open 
option is temporarily set to Input. INITIO 
is invoked to build new DECBs and initiate 
a read of the desired block. Then GET is 
invoked to calculate the next record 
address until the End of Buffer flag is on, 
at which time the data set is opened for 
Output, the original open option is 
restored, the DECB type code is reset to 
"write" , and Flush is invoked to purge out- 
standing read requests. Finally, for all 
OPEN options, the End of Buffer flag is set 
off, and a return is made to CZCSAS, which 
issues a RETURN macro instruction to 
restore the user's registers and link back 
to the problem program. 



SETL Type-E or -B (End or Beginning) ; The 
SETLEB subroutine makes an immediate return 
to CZCSAS, if the data set is opened for 
Output and type-E is specified. Otherwise, 
TREOV is invoked to clear all outstanding 
write requests. Then, if the device is 
direct access, register is set to zero 
for type-B, and Point is invoked to posi- 
tion the data set at the beginning or the 
end. 

If the device employs magnetic tape, and 
the data set is opened for Rdback, and 
type-B is specified, it must be spaced bac- 
kward to the end. If the data set is 
opened for Input, it must be spaced back- 
ward to the beginning for type-B, or spaced 
forward to the end for type-B. Control is 
invoked to perform the spacing of a data 
set on magnetic tape. 



When the data set is correctly posi- 
tioned, the Get and Put V-cons in DCBGTV 
arid DCBPTV, respectively, are set to CZCSAA 
and CZCSAB so that the next GET or PUT on 
the data set. Then a return is made to 
CZCSAS, which issues a RCTUUN macio 
instruction to restore the user's r<qist«rs 
and link back to the problem program. 

CLOSE and FEOV Functions Performed by QSAM 

During processing of a CIjOSE or FEOV 
macro instructions, the TREOV subroutine ot 
(QSAM) is used to perform those functions 
necessary to closinq out a volume or a data 
set, sucn as writing out the last buffer of 
an output data set, or purging any read 
requests which may have been issued on an 
input data set after the CLOSE or FEOV was 
issued. 



When it is being 
FEOV, TREOV is given 

entry section CZCSAV 
establishes type-1 1 

base registers for Q, 
control is passed to 
TREOV is also used i 
routines of QSAM dur 
QSAM macro instruct! 
whatever routine cal 



invoked by SAM Close or 

control by the QSAM 

SAM Close or FEOV 

inkaqe to CZCSAV, where 

SAM are established and 

TREOV. (Note that 
nternally by other sub- 
ing the processing of 
ons f and returns to 
led it.) 



If the data set has been opened for 
RDBACK or Input, the Flush subroutine of 
TREOV is invoked to purge outstanding 1/0 
requests, and upon return from Flush, the 
first Get or Put V-cons are moved into the 
DCB, and an immediate return is made to 
CZCSAV, or to the callinq subroutine. 

If the data set is opened for Output and 
the current buffer is empty, the last block 
of the data set has already been written 
out, and, if it has not yet been checked, 
the Check subroutine is invoked to perform 
the check . Otherwise, or upon return from 
Check, a return is made tc the entry rou- 
tine or to the calling subroutine- If the 
buffer is not empty, it must be written out 
as the last block of the data set. If the 
last PUT issued was in locate mode, and if 
the records are variable format, a check is 
made to be certain that the last record 
placed in the buffer does not overflow the 
end of the buffer. If it does, the task is 
abnormally terminated. Otherwise, the 
actual size of the block is calculated and 
PUTIO is invoked to write out the current 
buffer and check the previous write. Clf 
single buffering is bei nq done, PUTIO will 
write and check the same buffer.) Upon 
return from PUTIO, if any unchecked DECPs 
remain. Check is invoked to perform the 
check- Then a return is made to CZCSAV or 
to the calling subroutine. 

If the data set is opened for Update, 
and if no PUTX macro instruction has been 
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\ •., Vi*ed on the current block, TREOV gives 
control to Flush to purge any outstanding 
I/O requests, and then returns to the entry 

section or the calling subroutine. If a 
f-JTX has beer: issued on the current block , 
riowt-ver, the Head/Write subroutine is 

invoked to write the updated block back to 
the data set, and the Check subroutine is 

invoked to check on the completion of the 
write request. Then the return is made to 
the entry section or the calling 

subroutine. 
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PART IV 
RTAM/MTT ACCESS METHODS SUPPORT 



SECTION 1: MTT TERMINAL TASK CONTROL 



For the MTT user, there is a virtual 
storage routine (CZCTC) which performs 
functions analogous to access methods Read, 
Write, Find, or Close routines. The MTT 
command, through the command system, is 
processed by this routine, and the CLEARQ 
and FREEO macro instructions which clear 
pending work for a terminal and logically 
disconnect a terminal respectively. 



Terminal Task Control Routine CCZCTC) 



Word 1 — Address of a program name which 
is a maximum of 8-characters long. The 
byte preceding this address is a count 
of the characters in the name. 

Word 2 ~ Address of 4-byte count of the 
maximum number of terminals which may be 
simultaneously connected to the task 
(1-4095). 

Word 3 — Address of 3-byte schedule table 
level (1-255). 



The Terminal Task Control routine pro- 
vides an interface with the Terminal Com- 
munications Subprocessor in the resident 
supervisor. None of the macro instructions 
entered by the MTT user issue their own 
I/O, such as Read or Write. The method 
used by CZCTC is to set information into 
the application task's terminal control 
table (TCT) , and then to issue the ATCS 
macro instruction which calls the Terminal 
Control Subprocessor to perform the 
requested operation. 

When processing the MTT enable, communi- 
cation with the user is effected through 
PRMPT (CZATJ) in order to prompt the user 
for unentered or unacceptable parameters. 

The processors described are for the MTT 
command, and the FINDQ, READQ, WRITEQ, 
CLEARQ, and FREEQ macro instructions. Each 
has a separate entry point in CZCTC (Chart 
RA> . 

The subroutine, CZCTC7, tests the vali- 
dity of the device (line) number for each 
of the macro instructions (Chart RA) . 



MTT Enable 



Word 4 -- Address of 4 -byte count of the 
sue of the input buffer associated with 
each terminal line (16-4076), default 
200. 



Modules Called : Via type-2 linkage, unless 
specified: 

PRMPT (CZATJ1) — Prompt user for parame- 
ters, inform user of error. 

GETMAIN (CZCGA2) — Allocate necessary vir- 
tual storage. 

ABEND (CZACP1) — Abnormal task 
termination. 

FREEMAIN (CZCGA3) — Free virtual storage. 

There is also a type-1 call to the app- 
lication program named in the MTT command. 

Exits : 

Normal — Return to the calling routine. 

Error -- 

• Return to the calling routine after 
informing SYSOUT that the user is not 
authorized to issue MTT. 



Entry is the result of the MTT command 
given from a terminal, and passed through 
the command system. The application pro- 
gram is loaded, parameters are checked, the 
schedule table level is entered, and the 
virtual memory necessary for the task is 
reserved. When the application program is 
complete it is unloaded, the original sche- 
dule table level restored, and the virtual 
storage released. (The application program 
in this case is the control program for the 
multiterminal task operation (Chart RA) . ) 

Entry Point : CZCTC1 — From the command 
system via type-1 linkage. 

Input : Register 1 contains the address of 
a 4 -word parameter list: 



• Type-2 exit to SYSER followed by a 
return to the calling routine, if the 
return from a PRMPT call is an error 
code* 

• SYSER followed by ABEND, if a non-zero 
return code is received after a FREEQ 
ALL macro is issued. 

Operation : This text is keyed to the flow- 
chart for CZCTC (Chart RA) and is 
referenced by label. 

The authority of the user issuing the 
MTT is tested and the application program 
is loaded or prompted for. The user must 
have an f O' or f P' authority 
(A0O-A0OX-A01-AO2) . 
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The parameters are tested, and prompted 
tor if necessary ( AO 3-A17-AiaB) . 

The number of pages required by the task 

is computed and allocated* based on the 
naiaber of application buffer pages needed 
pi os the number of TCT pages necessary 
(A18-A18A). 

The CONN SVC is issued which transfers 
•...jntiol to CEARii to perform initialization 
in real-core. The roultitenztinal system 

control block (HT5CB) is built and the TCT 
ana, buffer page allocated* If the task is 
already MTT, it is returned to normal sta- 
tus and the CONK is reissued 
ITC1A-TC1B-TC1B1) . 

The current schedule table level is 
saved and the new level entered 
(TC1A-TC1C). 

The application program, which is the 
*€XT control program, is now dispatched via 
a type-1 call. 

Wiien trie MIT application returns, it is 
uiaodtiiid C DELETE) and FREEQ ALL is issued 
to logically disconnect the terminals. The 
DCON Macro cleans up main storage, the ori- 
ginal schedule table level is returned, and 
the virtual storage is freed, 

A return is made to the command system. 



FINDQ Macro 

FINDQ tests a specific line number, or 
polls the MTT application program's work 

queue (TCT) to find a terminal with work to 
be done. A return code specifying the work 
to be done, or that there is no work to do, 

is returned to the calling program. 



'08* Initial connection of device. 

1 0C f Attention from terminal. 

'10 s Solid I/O error on terminal line. 

*m 9 Message Out complete Cfrom previous 
WRITEQ) . 

s 18' Message In complete Cfrom previous 
WRITEQ/RESP). 

"1C 1 Negative response from input 
component. 

•20* Message In overflowed buffer* 

Operation s If polling is specified, the 
TCT slots are scanned for work starting 
with the slot after the halt of the pre- 
vious scan. The result is returned as a 
code in register 15* CSee *Exits* f ) 

CHAFNQ fields are set with the device 
type and symbolic device address. 

Message In also sets the length of the 
message and its address in CHAFNQ. 

If a specific line is to be tested, no 
polling takes place if there is no work in 
its TCT* 

A SYSER is issued if there is work in 
the TCT, but it cannot be identified. The 
SYSER is followed by a return to the user 
with a return code of X'OU*. 

READQ Macro 

READQ posts the read request and asso- 
ciated options in the TCT slot and passes 
control to the resident supervisor via 
ATCS. For any return code other than *00% 
the read operation has not been initiated. 



Entr y Point ; CZCTC2 -- Via type-1 linkage. Entry Point ; CZCTC3 — Via type-1 linkage. 



Input : Register 1 contains the address of 
CHAFNQ. FNQCTL (in CHAFQN) is a 2-byte 

field: 

FFFF -- Polling operation, 

XXXX -- Unique device number from 0000 
to a user-specified maximum. 
The system maximum is 4095. 

M odules Called : None. 

Exits: Return to the calling routine with 
one of the following codes in register 15: 

Cod e Condition 
■00' No work. 

'04 s Invalid relative line number (not 
connected to application) . 



Input ; Register 1 contains the address of 
CHARDQ. RDQDEV (in CHARDQ) is a 2-byte 
device (line) number. 

Modules Called ; None. 

Exits ; Return with a code in register 15; 

Code Condition 

•00* Normal completion. 

•04* Device number invalid, component 
select invalid. 

•08' Previous operation incomplete. 

"0C Attention from terminal. 

•10' Unrecoverable I/O error on terminal 
line. 
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Operation : The text is keyed to chart RA, 
Entry CZCTC3. References are by label. 

The device (line) number, and the Atten- 
tion and Previous Operation flags in the 
TCT are tested (Entry CZCTC3-TC3A) . 

Parameter fields are tested and set 
accordingly (TC3B-TC3G). The Interruption 
bit specifies that an application program 
will process external interruptions 
generated upon completion of a read opera- 
tion. The interruptions will be ignored if 
it is not set. 

The Component Select field specifies a 
type of 1050 unit: 

Any input component 

5 Terminal keyboard 

6 Reader 1 

7 Reader 2 

The Terminal Communications Subprocessor 
is invoked to perform the operation via 
ATCS f and upon completion the result is 
tested, and an appropriate code returned 
CTC3G-TC3J). 



WF X TEQ Macro 

WRITEQ posts the write requests and 
associated options in the application TCT 
slot and passes control to the resident 
supervisor via ATCS for execution. For any 
return code other than • 00 f , the write 
operation has not been initiated. 

Entry Point : CZCTC4 -- Via type-1 linkage. 

Input : Register 1 contains the address of 
CHAWRQ. WRQDEV (in CHAWRQ) is a 2- byte 
device (line) number. 

Modules Called : None. 

Exits : Return to the calling routine with 
a code in register 15: 

Code Condition 
•00* Normal return. 

'04 f Invalid relative line number, 
Component-Out field. 

■08" Busy, I/O outstanding, BIO not 
complete. 

'0C Attention interruption from 
terminal. 

* 10' Solid I/O error on line. 

*m* Message length not 1-4080 bytes. 



Operation : The text is keyed to the flow- 
chart (Chart RA, Entry CZCTCU) by label. 

The device (line) number, 'break 1 
option, outstanding I/O, and 'busy* options 
are tested (Entry CZCTC4-TC43A) - 

Parameter options are set in TCT 
(TCaa-TCUC) . 

The data is forced into core, and the 
ATCS macro issued to execute the write 
operation. The results are tested upon 
return from the resident supervisor, and a 
code set accordingly (TC4D-T<T4C3) . 



CLEARQ Macro 

The status byte of the application TCT 
slot is tested for work indications, and 
unless a READQ or WRITEQ is in progress, 
the contents of the TCT slot are saved and 
the byte is set to zero. 

Entry Point : CZCTC5 — Via type-1 linkage. 

Input : Register 1 contains the address of 
CHACLQ. CLQDEV (in CHACLQ) is a 2- byte 
device (line) number. 

Modules Called : None. 

Exits : Return to the calling program with 
a code in register 15: 

Code Condition 
"00* Normal return. 



•0*J' 



Invalid device (line) number. 



•08" Busy, previous READQ or 
WRITEQ not completed. 

•OC 9 Attention from line. 

Operation : The device number and •busy" 
indicator are checked. 

The work byte is saved, and the reset 
byte also. If a buffer is connected, ATCS 
is issued to perform the clear function 
(see Chart RA, labels TC51-TC5A1) . 

A return is made with the appropriate 
code. 



FREEQ Macro 

FREEQ will logically disconnect a spe- 
cific terminal, or all terminals associated 
with an application program. If specified, 
a message is written out to the terminal 
before disconnecting. A physical discon- 
nect may be requested, whereby the line to 
the device will be disabled — this is 
handled in the resident supervisor. 
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Ent ry Point : CZCTC6 -- Via type-1 linkage. 

Input: Register 1 contains the address of 
CHAFRQ. FRQDEV (in CHAFMQ) is a 2- byte 
device (line) number, 

ftp d u 1 e c Call < * d : Nonf. 

Exits : Return to the calling program with 
a code in register 15: 

Code Condi tion 

s 00* Normal return. 

"04* Invalid device (line) number. 



'OS 1 

r 0C f 

•10 s 



Disconnect speciiied not 
arid not 'physical'. 



iogica 1 s 



Message specified with zero length- 
Message address illegal. 



Qp eratxon ; If the ALL option is set and 
the disconnect valid (physical or logical), 
the message is tested and ATCS issued to 
perform the request. 

If a specific line is to be freed* the 
Free Function flag is set and the work byte 
cleared, before ATCS is issued. CSee Chart 
RA # Entry CZCTC6.) 
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Program Logic Manual 

GY28-2016-5 

Access Methods 



Flowcharts on pages 199-438 were not scanned. 



Chart RA. Terminal Task Control - CZCTC (Page 7 of 7) 



SUBROUTINE 




Flowcharts U39 
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CHAADC- Explicit adcon group 
used by: 

CZCTC-Terminal Task Control 

CHABCT-BULKOMK Table 
used by: 

CZCQK-VDMEP 

CHABPL-Buffer Page List 
used by: 

CZCMA-GETBUF 

CZCNA-FREEBUF 

CZCNB-FREEPOOL 

CHADBP-DEB Page 
us ed by : 

CZCMC-MSAM Open 

CZCMD-SETUR 

CZCME-DOMSAM 

CZCMG-MSAM Posting and Error Retry 

CZCMH-MSAM Finish 

CZCMI-MSAM Close 

CHACLQ-CLEARQ 
used by: 

CZCTC-Terminal Task Control 

CHADCB-Data Control Block 
used by: 

CZCLA-Open Common 

CZCLB-Close Common 

CZCID-FEOV 

CZCMA-GETBUF 

CZCMB-GETPOOL 

CZCMC-MSAM Open 

CZCMD-SETUR 

CZCME-DOMSAM 

C2CMF-MSAM Read/Write 

CZCMG-MSAM Posting and Error Retry 

CZCMH-MSAM Finish 

CZCMI-MSAM Close 

CZCNA-FREEBUF 

CZCNB-FREEPOOL 

CZCOA-OPENVAM 

CZCOB-CLOSEVAM 

CZCOC-MOVEPAGE 

CZCOD-Insert/Delete Page 

CZCOE-REQPAGE 

CZCOF- Insert 

CZCOG-Reclaim 

CZCOJ-Find 

CZCOK-Stow 

CZCOL-Search 

CZCOM-Extend POD 

CZCON-Relocate Members 

CZCOD-GETNUMBR 

CZCOP-VSAM Open 

CZCOQ-VSAM Close 

CZCOR-VSAM Get 

CZCOS-VSAM Put 

CZCOT-SETL 

CZCOU-PUTX 

CZCOV-FLUSHBUF 

CZCPA-VISAM Put 



CZCPB-VIS7\M Get 

CZCPC-SETL 

CZ CPE-Read/Write 

CZCPI-GETPAGE 

CZCPL-Add Directory Entry 

CZCPZ-VISAM Open 

CZCQA-VISAM Close 

CZCQE-Search SDST 

CZCQI-Expand RESTBL 

CZCQQ-VAM ABEND Interlock Release 

CZCRA-BSAM Read/Write 

CZCRB-Control 

CZCRC- Check 

CZCRG-Backspace 

CZCRM-Point 

CZCRN-Note 

CZCRP-SAM Posting and Error Retry 

CZCSA-QSAM 

CZCSB-IOREQ 

CZCSC-IOR Open 

CZCSD-IOR Close 

CZCSE-IOREQ Posting 

CZCWA-ASCII Translation and Conversion 

CZCWB-Build Common DEB 

CZCWC-SAM Close 

CZCWD-DAOPEN 

CZCWL-Build DA DEB 

CZCWO-SAM Open Mainline 

CZCWT-Tape Open 

CZCWY-Tape Data Set Label 

CZCXD-DA Output EOV 

CZCXE- Ma inline EOV 

CZCXI-DA Input EOV 

CZCXN-DA Input LABEL 

CZCXO-Tape Output EOV 

CZCXS-Set DSCB 

CZCXT-Tape Input EOV 

CZCXU-DA Output Label 

CZ CXX- Concat enat ion 

CZCYA-TAM Open 

CZCYG-TAM Close 

CZCYM-TAM Read/Write 

CZCZA-TAM Posting 

CHADEB-Data Extent Block 
used by: 

CZCLA-Open Common 

CZCLB-Close Common 

CZCLD- Force End of Volume 

CZCMA-GETBUF 

CZCMB-GETPOOL 

CZCMC-MSAM Open 

CZCMD-SETUR 

CZCME-DOMSAM 

CZCMF-MSAM Read/Write 

CZCMG-MSAM Posting and Error Retry 

CZCMH-MSAM Finish 

CZCMI-MSAM Close 

CZCNA-FREEBUF 

CZCNB-FREEPOOL 

CZCRA-BSAM Read/Write 

CZ CR B- Cont ro 1 

CZCRC-Check 

CZCRG-Backspace 
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CZCRM- 
CZCRN- 
CZCRP- 

CZCSA- 

CZCSB- 

C2CSO 
CZCSD- 
CZCSE- 

CZCWB- 

czcwc- 

CZCWD- 
CZCWL- 
CZCWM- 

czcwo- 

CZCWP- 

CZCWR- 

CZCWT- 

CZCWY- 

CZCXD- 

CZCXE- 

CZCXI- 

CZCXN- 

czcxs- 

CZCXT- 

czcxu- 
czcxx- 

CZCYA- 
CZCYG- 
CZCYM- 

CZCZA- 

CHADEODat 
used by: 
CZCMC- 
CZCME- 
CZCMF- 
CZCMG- 
CZCMH- 
CZCMI- 
CZCPE- 
CZCRA- 
CZCRB- 
CZCRC 
CZCRP- 
CZCSA- 
CZCSB- 

*:zcsd- 

C2C5E™ 

czcwc- 

CZCWO- 
CZCWY- 

CZCXE- 

czcxs- 

CZCYG- 
CZCYM- 

CZCZA- 



and Error Retry 



DEB 



Po i n t 
Not.«- 

SAM Posil 

QSAM 

1QR&J 

I OR Op»'-n 

IOP <:h . *: 
IOREQ Pc J ting 
Build Common 

SAM Close 

DAOPEN 

Bui Id DA DEB 

Mc»ssaqe Writer 

SAM Open Mainline 

Tape Positioning 

Read Format -3 DSCB 

Tape Open 

Tape Data Set Label 

DA Output EOV 

Mainline EOV 

DA Input EOV 

DA Input Label 

Set DSCB 

Tape Input EOV 

DA Output Label 

Concatenation 

TAM Open 

TAW Close 

TAM Read/Write 

TAM Posting 

a Event Control Block 

MS AM Open 

DOMSAM 

MSAM Read/Write 

MSAM Postinq and Error Retry 

MSAM Finish 

MSAM Close 

Read/Write 

BS AM Read /Write 

Control 

Check 

SAM Posting and Error Retry 

QSAM 

IQREQ 

IOH Close 

XOREQ Posting 

SAM Close 

SAW Open Mainline 

Tape Data Set Label 

Mainline EOV 

Set, DSCB 

TAM Close 

TAM. Read/Write 

TAM Posting 



CHAD'dD-nCB Header 
us ed by .? 

CZCLB-Close Common 

CZCCA-OPENVAM 

CZCOB-OLOSEVAM 

CZCOC-MOVEPAGE 

CZCOD-Insert/Delete Page 

CZCOE-REQPAGE 

CZCOF- Insert 

CZCOG-Reclaim 

CZCOJ-Find 

CZCOK-Stow 

CZ COL- Search 



CZCOM-Ext end POD 
CZCON-Re locate Members 

CZCOO-GETNUMBR 

CZCCP-VSAM Open 

CZCOQ-VSAM close 

CZCOR-VSAM Get 

CZCOS-VSAM Put 

CZCOT-SETL 

CZCGU-PUTX 

CZCOV-FLUSHBUF 

CZCFA-VJSAM Put 

cz cm- VI SAM Get 

CZCI-C-SETL 

CZ CPE-Read/Write 

CZCPI-GETPAGE 

CZCPL-Add Directory Entry 

CZCPZ-VISAM Open 

CZCQA-VISAM Close 

CZCQ I -Expand RESTBL 

CZCQK-VDMEP 

CZCQQ-VAM ABEND Interlock Release 

CBADSC-DSCB Format- 1 & -3 
used by: 

CZCWD-DAOPEN 
CZCWL-Build DA DEB 
CZCWO-SAM Open Mainline 
CZCWR-Read Format-3 DSCB 
CZCXD-DA Output EOV 
CZCXI-DA Input EOV 
CZCXS-Set DSCB 

CHADSV-DSCB Format- A fe -B 
used by: 

CZCOA-OPiiNVAM 
CZCOB-CLOSEVAM 

CHAEPE-RESTBL External Page Entry 
used by; 

CZCOC-MOVEPAGE 
CZCOE-REQPAGE 
CZCOF- Insert 
CZCOG-Reclaim 
CZCOO-GETNUMBR 

CHAFNQ-FINDQ 
used by; 

CZCTC-Terminal Task Control 

CHAFRQ-FREEQ 

used by; 

CZCTC-Terminal Task Control 

CHAGSM-General Services Macro Table 

used by: 

CZCLA-Open Common 
CZCLB-Close Common 

CHAICB-Interruption Control Block 
used by: 

CZCMC-MSAM Open 

CZCMD-SETUR 

CZCMG-MSAM Posting and Error Retry 

CZCMI-MSAM Close 

CHAIOR-I/O Request Control Block 
used by: 

CZCMC-MSAM Open 
CZCMD-SETUR 
CZCMF-MSAM Read/Write 
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CZCMG-MSAM Posting and Error Retry 

CZCMH-MSAM Finish 

CZCRA-BSAM Read/Write 

CZCRB- Control 

CZCRP-SAM Posting and Error Retry 

CZCSB-IOREQ 

CZCSE-IOREQ Posting 

CZCYM-TAM Read/Write 

CZCZA-TAM Posting 

CHAIS A- interruption Storage Area 
used by: 

CZCEI-VMIER 

CZCLA-Open Common 

CZCMA-GETBUF 

CZCMG-GETPOOL 

CZCMD-SETUR 

CZCME-DOMSAM 

CZCMF-MSAM Read/Write 

CZCMG-MSAM Posting and Error Retry 

CZCMH-MSAM Finish 

CZCNA-FREEBUF 

CZCNB-FREEPOOL 

CZCPA-VISAM Put 

CZCPB-VISAM Get 

CZCPC-SETL 

CZCQE-Search SDST 

CZCQK-VDMEP 

CZCQQ-VAM ABEND Interlock Release 

CZCRP-SAM Posting and Error Retry 

CZCSA-QSAM 

CZCSB-IOREQ 

CZCSE-IOREQ Posting 

CZCWD-DAOPEN 

CZCWO-SAM Open/Mainline 

CZCWT-Tape Open 

CZCWY-Tape Data Set Label 

CZCXE-Mainline EOV 

CZCXN-DA Input Label 

CZCYG-TAM Close 

CZCZA-TAM Posting 

CHALBl-Data Set Header/Trailer Label 1 

used by: 

CZCWM-Message Writer 
CZCWY-Tape Data Set Label 

CHALB2-Data Set Header/Trailer Label 2 

used oy: 

CZCWY-Tape Data Set Label 

CHAMHD-RESTBL Member Header 
used by: 

CZCOA-OPENVAM 

CZCOB-CLOSEVAM 

CZCOC-MOVEPAGE 

CZCOE-REQPAGE 

CZ CO J- Find 

CZCOK-Stow 

CZCON-Relocate Members 

CZCOO-GETNUMBR 

CZCQI-Expand RESTBL 

CZCQK-VDMEP 

CZCQQ-VAM ABEND Interlock Release 

CHAPOD- Partitioned Organization Directory 
used by: 

CZCOJ-Find * 

CZCOK-Stow 

CZCOL-Search 



CZCOM-Extend POD 
CZCON- Relocate Members 
CZCOO-GETNUMBR 

CHAPOE- Directory Alias Descriptor 
used by: 

CZCOJ-Find 
CZCOK-Stow 
CZCOL-Search 

CHAPOM-Directory Member Descriptor 
used by: 

CZCOJ-Find 

CZCOK-Stow 

CZCOL-Search 

CZCON- R*?locate Members 

CZCOO-GETNUMBR 

CHAPVT-Public/Private Volume Table 
used by: 

CZCEI-VMIER 

CHARDQ-READQ 
used by: 

CZCTC-Terminal Task Control 

CHARHD-RESTBL Header 
used by: 

CZCOA-OPENVAM 

CZCOB-CLOSEVAM 

CZCOC-MOVEPAGE 

CZCOD-Insert/Delete Page 

CZCOE-REQPAGE 

CZCOF- Insert 

CZCOG-Reclaim 

CZCOJ-Find 

CZCOK-Stow 

CZCOM-Extend POD 

CZCON- Re locate Members 

CZCOO-GETNUMBR 

CZCOP-OPENSEQ 

CZCOQ-CLOSESEQ 

CZCOR-VSAM Get 

CZCOS-VSAM Put 

CZCOT-SETL 

CZCOU-PUTX 

CZCPA-VISAM Put 

CZCPB-VISAM GET 

CZCPC-SETL 

CZCPE-Read/Write 

CZCPI-GETPAGE 

CZCPL-Add Directory Entry 

CZCPZ-VISAM Open 

CZCQA-VISAM Close 

CZCQI-Expand RESTBL 

CZCQK-VDMEP 

CZCQQ-VAM ABEND Interlock Release 

CHASAR-System Activity and Resource Table 
used by: 

CZCTC-Terminal Task Control 

CHASCB-SAM Communication Block 
used by: 

CZCWB-Build Common DEB 
CZCWC-SAM Close 
CZCWD-DAOPEN 
CZCWL-Build DA DEB 
CZCWM-Message Writer 
CZCWO-SAM Open Mainline 
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CZCWP-Tape Positioning 
CZCWR-Read Format-3 DSCB 
CZCWT-Tape Open 
cZCWV-Volume Sequence Convert 
CZCWY-Tape Data Set Label 
CZCXD-DA Output EOV 
CZCXE-Mainline EOV 
CZCXI-DA Input EOV 
CZCXN-DA Input Label 
CZCXO-Tape Output BOV 
CZCXS-Set DSCB 
CZCXT-Tape Input EOV 
CZCXU-DA Output Label 
CZCXX-Concatenation 



CHASDT-I/O Statistical Data Table 
us ed by: 

CZCMG-MSAM Posting and Error Retry 
CZCRP-SAM Posting and Error Retry 

CHATCM-Tas.k Common Table 
used by z 

CZCEI-VMIER 
CZCQK-VDMEP 
CZCTC- Terminal Task Control 

CHATCT -Terminal Control Table 
us ed by : 

CZCTC-Terminal Task Control 



CHASDA- Symbolic Device Allocation 
used by: 

CZCEI-VMIER 

CZCMC-MSAM Open 

CZCMD-SETUR 

CZCMG-MSAM Posting and Error Retry 

CZCMI-MSAM Close 

CZCQK-VDMEP 

CZCRA-BSAM Read/Write 

CZCRB-Control 

CZCRC-Check 

CZCRG-Backspace 

CZCRP-SAM Posting 

CZCSC-IOR Open 

CZCWB-Build Common DEB 

CZCWC-SAM Close 

CZCWD-DAOPEN 

CZCWL-Build DA DEB 

CZCWM-Message Writer 

CZCWP-Tape Positioning 

CZCWY-Tape Data Set Label 

CZCXS-Set DSCB 

CZCYA-TAM Open 

CZCYG-TAM Close 

CZCYM-TAM Read/Write 

CZCZA-TAM Posting 

CHASDE-Shared Data Set Entry 
used by: 

CZCOA-OPENVAM 

CZCOB-CLOSEVAM 

CZCQE-Search SDST 

CZCQK-VDMEP 

CZCQQ-VAM ABEND Interlock Release 

CHASET-BULKIO S-Entry Table 
us ed by : 

CZCQK-VDMEP 

CRASDM-Shared Data Set Member 
used by: 

CZCOA-OPENVAM 

CZCOB-CLOSEVAM 

CZCQE-Search SDST 

CZCQK-VDMEP 

CZCQQ-VAM ABEND Interlock Release 



CHATDT-Task Data Definition Table 

used by: 

CZCEI-VMIER 

CZCLA-Open Common 

CZCLB-Close Common 

CZCMC-MSAM Open 

CZCMI-MSAM Close 

CZCOA-OPENVAM 

CZCOB-CLOSEVAM 

CSCOE-REQPAGE 

CZCQE-Search SDST 

CZCQi-Expand RESTBL 

CZCQK-VDMEP 

CZCQQ-VAM ABEND Interlock Release 

CZCSC-IOR Open 

CZCWB-Build Common DEB 

CZCWC-SAM Close 

CZCWD-DAOPEN 

CZCWL-Build DA DEB 

CZCWM-Message Writer 

CZCWO-SAM Open Mainline 

CZCWP-Tape Positioning 

CZCWT-Tape Open 

CZCWY-Tape Data Set Label 

CZCXD-DA Output EOV 

CZCXE-Mainline EOV 

CZCXI-DA Input EOV 

CZCXO-Tape Output EOV 

CZCXS-Set DSCB 

CZCXT-Tape Input EOV 

CZCXX-Concatenation 

CZCVA-TAM Open 

CZCYG-TAM Close 

CHATOS-Terminal Access Operational Status 

Table 
us ed by : 

CZCYM-TAM Read/Write 
CZCZA-TAM Posting 

CHAVPS-Virtual Program Status Word 
us ed by : 

CZCMA-GETBUF 
CZCMB-GETPOOL 
CZCNA-FREEBUF 
CZCNB-FREEPOOL 
CZCRA-BSAM Read/Write 



CHASDS-Shared Data Set Table 
used by: 

CZCOA-OPENVAM 

CZCOB-CLOSEVAM 

CZCQE-Search SDST 

CZCQK-VDMEP 

CZCQQ-VAM ABEND Interlock Release 



CHAWRQ-WRXTEQ 
used by: 

CZCTC -Terminal Task Control 

QWKAR-QSAM Work Area 
used 'by : 

CZCSA-QSAM 
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APPENDIX B: MODULES CALLED BY ACCESS METHODS MODULES 



CEAAC-ADDEV 



CEAAD-RMDEV 



Access Methods Modules That 

Call this Module : 

CZCYA - TAM Open 
CZCYG - TAM Close 



Module 



CZCYA 
CZCYG 



TAM Open 
TAM Close 



Access Methods Modules That 

Call this Module 

CZCOR - VSAM Get 
CZCSB - IOREQ 
CZCSC - IOR Open 
CZCYM - TAM Read/Write 



CEAAK- SETAE 



CEAAO-I/O 
CALL 



CEAAH- Reset CZCMD - SETUR 

CZCMF - MSAM Read/Write 

CZCMH - MSAM Finish 

CZCRP - SAM Posting 

CZCSE - IOREQ Posting 

CZCZA - TAM Posting 

CZCRA - DA Error Retry 
CZCYG - TAM Close 

CZCMF - MSAM Read/Write 

CZCRA - BSAM Read/Write 

CZCRB - Control 

CZCRP - SAM Posting 

CZCSB - IOREQ 

CZCYM - TAM Read/Write 

CZCZA - TAM Posting 

CZCOC - MOVEPAGE 

CZCOD - Insert/Delete Page 

CZCOH - Interlock 

CZCOI - Release Interlock 

CZCOJ - Find 

CZCOK - Stow 

CEAH3-XTRCT CZCRH - DA Error Retry 
CZCYG - TAM Close 

CEAH7-SETXP CZCOC - MOVEPAGE 



CEAHQ-LSCHP/ 
TSEND 



CEAIS- 


-SYSER 


CZCMF 


- 


MSAM Read/Write 






CZCMG 


— 


MSAM Posting and 
Error Retry 






CZCRP 


- 


SAM Posting 






CZCYG 


- 


TAM Close 






CZCZA 


- 


TAM Posting 


CRAP4- 


-LVPSW 


CZCRA 


- 


BSAM Read/Write 


CEAP7- 


-AWAIT 


CZCMI 


• 


MSAM Close 






CZCRA 


- 


BSAM Read/Write 






CZCRB 


_ 


Control 






CZCRC 


- 


Check 






CZCSD 


- 


IOR Close 






CZCWC 


- 


SAM Close 






czcwo 


- 


SAM Open Mainline 






CZCXE 


- 


Mainline EOV 


CEAP9- 


-TSEND 


CZCYM 


- 


TAM Read/Write 


CEAQ4- 


-CKCLS 


CZCMA 


- 


GETBUF 






CZCMC 


- 


MSAM Open 






CZCNB 


- 


BSAM Read/Write 






CZCOI 


- 


Release Interlock 



CEARO-TWAIT 


CZCRC 


- 


Check 


CEAA1-PGOUT 


CZCOB 


- 


CLOSEVAM 


CZAAB-Gate 


CZCWM 


- 


Message Writer 


CZABQ-WTO 


CZCMD 


- 


SETUR 




CZCMG 


— 


MSAM Posting and 
Error Retry 




CZCMH 


- 


MSAM Finish 




CZCRH 


- 


DA Error Retry 




CZCWM 


- 


Message Writer 




CZCYA 


- 


TAM Open 




CZCYG 


- 


TAM Close 




CZCZA 


- 


TAM Posting 


CZACP- ABEND 


CZCOA 


- 


OPENVAM 




CZCOB 


- 


CLOSEVAM 




CZCOC 


- 


MOVEPAGE 




CZCOD 


- 


Insert/Delete Page 




CZCOE 


- 


REQPAGE 




CZCOJ 


- 


Find 




CZCOK 


- 


Stow 




CZCOM 


- 


Extend POD 




CZCOO 


- 


GETNUMBR 




CZCOP 


- 


VSAM Open 




CZCOR 


- 


VSAM Get 




CZCOS 


- 


VSAM Put 




CZCOT 


- 


SETL 




czcou 


- 


PUTX 




CZCPA 


- 


VISAM Put 




CZCPB 


- 


VISAM Get 




CZCPC 


- 


SETL 




CZCPE 


- 


Read/Write 




CZCPI 


- 


GETPAGE 




CZCPL 


- 


Add Directory Entry 




CZCPZ 


- 


VISAM Open 




CZCQE 


- 


Search SDST 




DZCYA 


- 


TAM Open 




CZCYG 


- 


TAM Close 




CZCYM 


- 


TAM Read/Write 


CZAEB- 


CZCLA 


- 


Open Common 


FINDJFCB 








CZ CAB- Bump 


CZCXD 


- 


DA Output EOV 




CZCXI 


- 


DA Input EOV 




czcxo 


- 


DA Input Label 




CZCXT 


- 


Tape Input EOV 




CZCXX 


- 


Concatenation 




CZCWD 


- 


DAOPEN 




CZCWT 


- 


Tape Open 



CZCAP-ABEND CZCRP - SAM Posting 
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CZCEG-GIVBKS CZCWC - SAM Close 



Module 
CZCJS-SIR 



CZCEV-GIVBKV CZCOB 



CLOSEVAM 



CZCEK-Extend CZCOE - REQPAGE 

CZCXD - DA Output EOV 



CZCFO- Obtain/ CZCWD 
Retain CZCWR 
CZCXD 
CZCXI 
CZCXN 
CZCXS 

czcxu 

CZCOA 
CZCOB 



CZCGA-VMA 



CZCLA 
CZCLB 
CZCMA 
CZCMC 
CZCMI 
CZCGA 
CZCRH 
CZCNB 
CZCOA 
CZCOB 
CZCOC 
CZCOP 
CZCPE 
CZCPL 
CZCPZ 
CZCOM 
CZCQI 
CZCSC 
CZCSD 
CZCWB 
CZCWC 
CZCWD 
CZCWL 
CZCWO 
CZCWR 
CZCWT 
CZCXE 
CZCYA 
CZCYG 

CZCffi) 
CZCMF 
CZCMG 

CZCMH 
CZCMI 
CZCRP 
CZCSD 



C2CJI-INTINQ CZCMI 
CZCRP 



CZCJD-DIR 



CZCJL-LVPRV 



CZCWD 
CZCWO 
CZCWT 
CZCWY 
CZCXN 
CZCXU 
CZCYA 



DAOPEN 

Read Format- 3 DSCB 

DA Output EOV 

DA Input EOV 

DA Input Label 

Set DSCB 

DA Output Label 

OPENVAM 

CLOSEVAM 

Open common 
Close Common 
GETBUF 

MS AM Open 

MSAM Close 

VMA 

DA Error Retry 

FREEPOOL 

OPENVAM 

CLOSEVAM 

MOVEPAGE 

OPENS EQ 

Read/Write 

Add Directory Entry 

V1SAM Open 

Extend POD 

Expand RESTBL 

lOR Open 

IOR Close 

Build Common DEB 

SAM Close 

DAOPEN 

Build DA DEB 

SAM Open Mainline 

Read Format- 3 DSCB 

Tape Open 

Mainline EOV 

TAM Open 

TAM Close 

SETUR 

MSAM Read/Write 
MSAM Posting and 
Error Retry 
MSAM Finish 
MSAM close 
SAM Posting 
IOR Close 

MSAM Close 
SAM Posting 

DAOPEN 

SAM Open Mainline 

Tape Open 

Tape Data Set Label 

DA input Label 

DA Output Label 

TAM Open 



CZCJT-QLE 



CZCLA- Common 
Open 

CZCLB- Common 
Close 

CZCMA-GETBUF 

CZCMC- MSAM 
Open 

CZCMF- MSAM 

Read/Write 

CZCMH-MSAM 

Finish 

CZCMI-MSAM 
Close 

CZCOA-VAM 
Open 

CZCOB-VAM 
Close 

CZCOC- 

MOVEPAGE 



CZCOD- Insert/ 
Delete Page 



CZCOE- REQPAGE 



CZCOF-insert 



CZCOG-Reclaim 



CZCOH- 

Interlock 



Access Methods Modules That 
Call this Module 

CZCMD - SETUR 

CZCMG - MSAM Posting and 

Error Retry 
CZCMH - MSAM Finish 
CZCRH - DA Error Retry 
CZCRP - SAM Posting 

CZCRH - DA Error Retry 
CZCRP - SAM Posting 

CZCMD - SETUR 

CZCXX - Concatenation 

CZCMD - SETUR 

CZCXX - Concatenation 

CZCZA - GETBUF 

CZCLA - Open Common 

CZCME-DOMSAM 

CZCMI - MSAM Close 

CZCLB - Close Common 

CZCLA - Open Common 

CZCLB - Close Common 



CZCOA - OPENVAM 
CZCOB - CLOSEVAM 
CZCOR - VSAM Get 
CZCOS - VSAM Put 
CZCOT - SETL 
CZCOV - FLUSHBUF 
CZCPI - GETPAGE 
CZCQA - VISAM Close 

CZCOS - VSAM Put 

CZCOV - FLUSHBUF 

CZCPI - GETPAGE 

CZCPL - Add Directory Entry 

CZCOA - OPENVAM 
CZCOC - MOVEPAGE 
CZCOF - Insert 

CZCOD - Insert/Delete Page 
CZCOM - Extend POD 
CZCOO - GETNUMBR 

CZCOD - Insert/Delete Page 

CZCOK - Stow 
CZCOO - GETNUMBR 

CZCOA - OPENVAM 

CZCOC - MOVEPAGE 

CZCOD - Insert/Delete Page 

CZCOJ - Find 
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Access Methods Modules That 



Module 


Call this Module 




Modu le 
CZCPB- 


Call this Module 




CZCOK 


- 


Stow 




CZCPC 


- 


SETL 




CZCOO 


- 


GETNUMBR 




VISAM Get 










CZCQE 




Search SDST 




CZCPC- SETL 


CZCOJ 
CZCPE 


- 


Find 

Read/Write; DELREC 


CZCOI-Release 


CZCOA 


- 


OPENVAM 












Interlock 


CZCOC 


- 


MOVEPAGE 




CZCPE-Read/ 


CZCMD 


- 


SETUR 




CZCOD 


- 


Insert/Delete 


Page 


Write; 


CZCPA 


- 


VISAM Put 




CZCOJ 


- 


Find 




DELREC 


CZCPI 


- 


GETPAGE 




CZCOM 


- 


Extend POD 














CZCOO 


- 


GETNUMBR 




CZCPI-GETPAGE 


CZCPA 


- 


VISAM Put 




CZCQE 


- 


Search SDST 






CZCPB 


- 


VISAM Get 




CZCQQ 


- 


VAM ABEND Interlock 




CZCPC 


- 


SETL 








Release 






CZCPE 


- 


Read/Write; DELREC 


CZCOJ-Find 


CZCMD 


. 


SETUR 




CZCPZ- 


CZCOA 


- 


OPENVAM 




CZCOB 


- 


CLOSE VAM 




VI SAM Open 


CZCOJ 


- 


Find 


CZCOK-Stow 


CZCOJ 


- 


Find 




CZCQA- 


CZCOB 


- 


CLOSEVAM 




CZCQQ 


- 


VAM ABEND Interlock 


VI SAM Close 


CZCOK 


- 


Stow 








Release 




CZCQE- 


CZCOA 


— 


OPENVAM 


CZCOL-Search 


CZCOJ 


- 


Find 




Search SDST 


CZCOB 


- 


CLOSEVAM 




CZCOK 


- 


Stow 






CZCOK 


- 


Stow 




CZCOO 


_ 


GETNUMBR 






CZCQQ 


— 


VAM ABEND Interlock 
Release 


CZCOM-Extend 


CZCOK 


- 


STOW 












POD 










CZCQF-JFCBVUD 


CZCOB 
CZCOE 


_ 


CLOSEVAM 
REQPAGE 


CZCON- 


CZCOM 


- 


Extend POD 












Relocate 


CZCOO 


- 


GETNUMBR 




CZCQI - 


CZCOA 


- 


OPENVAM 


Members 










Expand 
RESTBL 


CZCOC 
CZCOE 


— 


MOVEPAGE 
REQPAGE 


CZCOO- 


CZCOC 


- 


MOVEPAGE 






CZCOJ 


- 


Find 


GETNUMBR 


CZCOD 


- 


Insert/Delete 


Page 




















CZCRA-SAM 


CZCRC- 


Check 


CZCOP- 


CZCOA 


- 


OPENVAM 




Read/Write 


CZCSA- 


■QSAM 


VSAM Open 


CZCOJ 


— 


Find 






CZCWY- 
CZCXS- 


Tape Data Set Label 
-Set DSCB 


CZCOQ- 


CZCOB 


- 


CLOSEVAM 












VSAM Close 


CZCOK 


_ 


Stow 




CZCRB-Control 


CZCRC 
CZCSA 


_ 


Check 

QSAM 


CZCOR- 


CZCOP 


- 


VSAM Open 






CZCWY 


- 


Tape Data Set Label 


VSAM Get 












CZCXS 


— 


Set DSCB 


CZCOS- 


CZCOP 


- 


VSAM Open 




CZCRC-Check 


CZCYA 


- 


TAM Open 


VSAM Put 


CZCOQ 


- 


VSAM Close 






CZCYG 


- 


TAM Close 




CZCOT 


- 


VSAM SETL 






CZCSA 


• 


QSAM 


CZCOT- SETL 


CZCOJ 
CZCOP 


- 


Find 
VSAM Open 




CZCRG- 

Backspace 


CZCSA 


- 


QSAM 


CZCOU-PUTX 


CZCOP 


- 


VSAM Open 




CZCRH-DA 

Error Retry 


CZCRP 


- 


SAM Posting 


CZCOV- 


CZCOQ 


- 


VSAM Close 












FLUSHBUF 


CZCOR 


- 


VSAM Get 




CZCRM- Point 


CZCWL 


- 


Build DA DEB 




CZCOS 


- 


VSAM Put 






CZCSA 


- 


QSAM 




CZCOT 


- 


SETL 














CZCOU 


- 


PUTX 




CZ CRN- Note 


CZCSA 


- 


QSAM 


CZCPA- 


CZCPA 


- 


VISAM Put 




CZCRQ-FINDR 


CZCRG 


- 


Backspace 


VISAM Put 


CZCLB 


- 


VISAM Get 














CZCPC 


- 


SETL 




CZCRR-RELFUL 


CZCRM 


- 


Point 




C2CPE 


- 


Read/Write; DELREC 












CZCPI 


- 


GETPAGE 




CZCRS-FULREL 


CZCRN 


- 


Note 




CZCQA 


- 


VISAM Close 






CZCXS 


- 


Set DSCB 



4*46 



Module 

CZCRX-VMER 



CZCRY-VMSDR 



CZCSA-QSAM 
FEOV 

CZCSC-IOR 
Open 

CZCSD-IOR 

Close 

CZCTJ- Prompt 



CZCWB-Buiid 
Common DEB 



Access Methods Modules That 

Call this Module 
CZCMG - MSAM Posting and 

Error Retry 
CZCRP - SAM Posting 
CZCZA - TAK Posting 

CZCMG - MSAM Posting and 

Error Retry 
CZCRP - SAM Posting 
CZCZA - TAM Posting 

CZCLD - Force End of Volume 



CZCWC-SAM 

Close 



CZCLA - Open Common 



CZCLB - Close Common 
CZCXI - DA Input EOV 

CZCWY - Tape Data Set Label 
CZCXI - DA Input EOV 

CZCWL - Build DA DEB 
CZCWO - SAM Open Mainline 
CZCWT - Tape Open 
CZCXE - Mainline EOV 
CZCXO -Tape Output EOV 
CZCXT - Tape Input EOV 

CZCLB - Close Common 



CZCWD-DAOPEN CZCWO - SAM Open Mainline 



CZCWL- Bui Id 
DA DEB 



CZCWM- 
Message 
Writer 



CZCWD - DAOPEN 

CZCXD ~ DA Output EOV 

CZCXI - DA Input EOV 

CZCWP - Tape Positioning 
CZCXD - DA Output EOV 
CZCXN - DA Input Label 

CZCXX - Concatenation 



CZCWO- SAM 
Open 

CZCWP-Tape 

Positioning 

CZCWR-Read 
Format-3 
DSCB 

CZCWT-Open 

Tape 



CZCLA - Open Common 

CZCWC - SAM Close 

CZCWD - DAOPEN 

CZCWX - DA Output EOV 

CZCWO - SAM Open Mainline 



Modul e 

CZCWV- 
Volume 
Sequence 

Convert 
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Call this Module 

CZCWC - SAM Close 
CZCWO - SAM Open Mainline 
CZCWY - Tape Data Set Label 
CZCXD - DA Output EOV 
c zc X K - Ma i n 1 i n o KO V 
CZCXI - DA Input EOV 
CZCXO - Tape Output EOV 
CZCXT - Tape Input EOV 



CZCXD- DA 

Output EOV 



CZCXE-SAM 
Mainline. 1 
EOV 

CZCXI-DA 
input EOV 

CZCXN- DA 

Input Label 

CZCXO- TAPE 
Output EOV 

CZCXS™Set 
DSCB 



CZCXT-Tape 
input EOV 

CZCXU-DA 
Output 
Label 

CZCXX- 
Concatena- 
tion 

CZCYA-TAM 

Open 

CZCYG-TAM 
Close 

CZCYM-TAM 
Write 



SVC-REDTIM 
SYSKA1-TIME 



CZCXE 



Mainline EOV 



CZCLD - Force End of Volume 
czcrc - Check 
CZCWC - SAM Close 

CZCXE - Mainline EOV 



CZCWD - DAOPEN 



CZCXE - Mainline EOV 



CZCWC - SAM Close 
CZCXD - DA Output EOV 
CZCXI - DA Input EOV 

CZCXE - Mainline EOV 



CZCWD - DAOPEN 

CZCXD - DA Output EOV 

CZCXE - Mainline EOV 
CZCXI - DA Input EOV 
CZCXT - Tape Input EOV 

CZCLA - Open Common 



CZCLB - Close Common 

CZCYA - TAM Open 
CZCYG - TAM Close 
CZCZA - TAM Posting 

CZCMD - SETUR 

CZCWY - Tape Data Set Label 
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APPENDIX C: ACCESS METHODS MODULE DIRECTORY 



This appendix provides an alphabetic listing of the various modules that are used in the 
Access Methods, Also provided are the C3ECT, PSECT, entry points and chart ID of each 

module. 



i Module 

1 ID 

| CZCEI 



CZCEY 
CZCEZ 
CZCFT 
CZCLA 
CZCLB 
CZCLD 
CZCMA 

CZCMB 

CZCMC 
CZCMD 

CZCME 

CZCMF 
CZCMS 

CZCMH 

CZCMI 
CZCNA 

CZCNB 

CZCOA 
CZCOB 
CZCOC 



CSECT 

CZCEI1 



Module Name 
VMIER 
DUPOPEN 
DUPCLOSE 
DELVAM 
OPEN COMMON 
CLOSE COMMON 
FORCED END OF VOLUME 
GET A BUFFER 

GET A BUFFER POOL 

MSAM OPEN 

SET UNIT RECORD 

DOMSAM 

MSAM READ/WRITE 

MSAM POSTING AND ERROR RETRY 

MSAM FINISH 

MSAM CLOSE 
FREE A BUFFER 

FREE A BUFFER POOL 

OPEN VAM 
CLOSE VAM 
MOVEPAGE 



CZCEIC 
CZCEYC 
CZCEZC 
CZCFTC 
CZCLAC 
CZCLBB 
CZCLDC 
CZCMAC 

CZCMBB 

CZCMCC 
CZCMDC 

CZCMEC 

CZCMFC 
CZCMGC 

CZCMHC 

CZCMIC 

CZCMBB 

CZCNBA 

CZCOAC 
CZCOBC 
CACOCC 



PSECT 

CZCEIP 

CZCEYP 

CZCEZP 

CZCFTP 

CZCLAB 

CZCLBP 

CZCLDB 

CZCMAB 

CZCMBP 

CZCMCP 
CZCMDP 



CZCMFP 
CZCMGP 

CZCMHP 

CZCMIP 
CZCMBP 

CZCNBB 

CZCOAP 
CZCOBP 
CZCOCP 



Entry 
Points 



CZCEY1 

CZCEZ1 

CZCFT1 

CZCLAO 

CZCLBC 

CZCLDF 

CZCMAG 
SYSMAG 
CZCMAB 

CZCMBG 
SYSMBG 
CZCMBP 

CZCMC1 

CZCMD1 
CZCMD2 
CZCMD3 

CZCME1 
CZCME2 

CZCMF1 

CZCMG1 
CZCMG2 

CZCMH1 
CZCMH2 
CZCMH3 

CZCMI1 

CZCNAF 
SYSNAF 
CZCNAP 

CZCNBC 
SYSNBC 
CZCNBB 

CZCOA1 

CZCOB1 

CZCOC1 






Chart ID 
JB 
MB 
MF 
KF 
AA 
DA 
FA 
HB 

HA 

AI 
AJ 

BB 

BC 
CC 

DC 

DD 
HC 

HD 

MA 
ME 
JA 
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Module 
ID 

CZCOD 



CZCOE 
CZCOF 
CZCOG 
CZCOH 
CZCOI 
CZCOJ 
CZCOK 
CZCOL 

CZCOM 
CZCON 
CZCOO 
CZCOP 
CZCOQ 
CZCOR 
CZCOS 

CZCOT 
CZCOU 

czcov 

CZCPA 

CZCPB 
CZCPC 

CZCPE 

CZCPI 



CZCPL 
CZCPZ 
CZCQA 
1 CZCQE 



Module Name 

INSERT PAGE 
DELETE PAGE 

REQUEST PAGE 

INSERT 

RECLAIM 

INTERLOCK 

RELEASE INTERLOCK 

FIND 

STOW 

SEARCH 

EXTEND POD 
RELOCATE MEMBERS 
GETPAGE NUMBER 
OPEN SEQUENTIAL 
CLOSE SEQUENTIAL 
VSAM GET 
VSAM PUT 

SET LOCATION 
PUT EXCHANGE 
FLUSH BUFFER CS) 
VI SAM PUT 

VISAM GET 
SET LOCATION 



READ/WRITE 
DELETE-RECORD 

GETPAGE 

END SEQUENTIAL 

RELEASE EXCLUSIVE 



ADD DIRECTORY ENTRY 
VISAM OPEN 
VISAM CLOSE 
SEARCH SDST 



I 



CSECT 



CZCODC [ 

I 

I i 

1 CZCOEC | 

I I 

| CZCOFC J 

I i 

| CZCOCC I 

1 i 

I CZCOHC I 

i 1 

I CZCOIC I 

I i 

i CZCOJC i 

I I 

1 CZCOKC 1 

! 1 

I CZCOLC 1 

I 1 

I I 

i CZCOMC i 



i 

PSECT I 

CZCODP I 



CZCOEP | 

1 
CZCOFP | 

I 
CZCOGP | 

I 
CZCOHP j 

i 

CZCOIP i 

CZCOJP i 

i 
CZCOKP I 

I 

None i 



CZCOMC | 

1 
CZCOOC i 

i 
CZCOIC i 

1 

CZCOQC 1 

I 
CZCORC i 

i 

CZCOSC | 



| CZCOTC I 

I I 

I CZCOUC I 

l i 

j CZCOVC I 

t I 

S CZCPAC i 

1 1 

i I 

j CZCPBC I 

I I 

I CZCPCC j 



I CZCPEC 



CZCOMP 

None 

CZCOOP 

CZCOPP 

CZCOQP 

None 

None 

None 
None 
CZCOVP 

None 

None 

None 

CZCPEP 



I 



j CZCPIC 1 CZCPIP 

i I 

I I 

1 I 

I 1 

I j 

j CZCPLC I CZCPLP 

I ! 

| CZCPZC I CZCPZP 

I I 

I CZCQAC ( CZCQAP 

i I 

| CZCQEC | CZCQEP 



Entry | 
Points j 

CZCOD1 | 

CZCOD2 | 

I 
CZCOE1 | 

I 
CZCOF1 | 

I 
CZCOG 1 ( 

t 
CZCOH1 | 

I 
CZCOI1 I 

I 

CZCOJ 1 I 
CZCOK 1 i 

I 

CZCOL1 ! 
CZCOL2 | 

i 

CZCOM1 | 

I 

CZCON1 1 

I 
CZCOOl i 

{ 

CZCOP1 I 
CZCOQ1 i 

i 

CZCOR1 I 

I 

CZCOS1 j 
CZCOS 2 I 



I CZCOT 1 I 

1 ! 

I CZCOU1 j 

S I 

I CZCOV1 i 

1 I 

j CZCPA1 i 
S CZCPA2 1 

1 I 

I CZCPB1 I 

I 1 

I CZCPC1 j 
! CZCPC2 I 

I 

CZCPE1 ! 
CZCPH1 I 

i 

CZCPI1, i 

CZCPI2, 1 

CZCPI3, t 

CZCPD1, I 

CZCPG1 I 

I 

CZCPL1 1 

I 

CZCPZ1 i 

1 

CZCQA1 j 

! 

CZCQE1 1 



I 
Chart ID j 

KA I 



KD 
KB 
KE 
LA 

LB 
PA 

PB 
PC 

PD 
PE 
PF 
MC 
MG 
NA 
NB 

NC 
ND 

NE 

OA 

OB 

OC 

OD 
OE 



OF 
MD 

MB 
JD 
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Module 
ID 

CZCQI 



CZCQK 

CZCQQ 
CZCRA 

CZCRB 
CZCRC 
CZCRG 
CZCRH 
CZCRM 

CZCRN 

CZCRP 

CZCRQ 
CZCRR 

CZCRS 

CZCSA 



Module Name 
EXPAND RESTBL 
VDMEP 



VAM ABEND INTERLOCK RELEASE 
BSAM READ/WRITE 

TAPE CONTROL 

CHECK I/O 

BACKSPACE 

DA ERROR RETRY 

LOGICALLY REPOSITION TAPE OR 
DA DATA SET 

NOTE ID OF LAST RECORD READ 
OR WRITTEN 

SAM POSTING AND ERROR RETRY 

FIND RECORDS PER TRACK 
RELFUL 

FULREL 

GET (The first GET following a 
SETL type E or B, the first 
GET following a FEOV, or the 
first GET on a data set,) 

PUT (Entered for the Same PUT 
macro instruction as GET 
above.) 

GET (All tnose not covered 
above.) 

PUT 

SETLB f E 

SETLR 

COMIO 

SET LP 

SETL 

SAM CLOSE or FEOV 



CSECT 

CZCQEC 

CZCQKC 

CZCQEC 
CZCRAC 

CZCRBC 
CZCRCC 
CZCRGC 
CZCRHC 
CZCRMC 

CZCRNS 

CZCRPC 



PSECT 

+ + 

CZCQEP 

CZCQKP 



CZCQEP 
CZCRAP 

CZCRBP 
CZCRCP 
CZCRGP 
CZCRHP 
CZCRMP 

CZCRNP 

CZCRPR 



1 

Entry 
Points i 
_ j 


r 

Chart ID 


CZCQE1 


KC 


CZCQK 1 
CZCQK 2 
CZCQKJ 


JC 


CZCQQ1 


Ml 


CZCRES, 
CZCRAS, 
CZCRDS 


BA 


CZCRBS 


GD 


CZCRCS 


CF 


CZCRGA 


GC 


CZCRH1 


CB 


CZCRMA 


GB 


CZCRNA 
SYSRNA 


GA 


CZCRPl 
CZCRP2 


; ca 


CZCRQA 


ID 


CZCRRA 
SYSRRA 


IE 


CZCRSA 
SYSRSA 


IF 


CZCSAA 


QA 


CZCSAB 




CZCSAG 




CZCSAW 




CZCSAH 




CZCSAL 




CZCSAM 




CZCSAQ 




CZCSAS 




CZCSAV 
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t CZCSA 


SETLC 
PUTX 

TRUNC 

RELSE 

INITIO 

GET 

PUT 

TREOV 






| CZCSAZ | 

1 

| CZCSA2 

1 

| CZCSA 3 

| CZCSAU 

t 

| CZCSA6 

t CZCSA7 

1 

| CZCSA8 

1 

( CZCSA9 

i 


. 

Qk 


1 

I 
1 

I 

i 

1 

! 
i 

i 
i 
1 

1 

l 

1 

I 


| CZCSB 
| CZCSC 


IOREQ 
IOR OPEN 


CZCSBC 
CZCSCC 


CZCSBP 
CZCSCP 


1 

| CZCSBl 

| CZCSB2 

| CZCSC1 

i 


BE 
AL 


1 

! 

1 
i 


1 CZCSD 


| IOR CLOSE 


CZCSDC 


CZCSDP 


1 

| CZCSDl 


DF 


1 
j 


| CZCSE 


IOREQ POSTING 


CZCSEC 


CZCSER 


{ 

| CZCSE1 


CE 


i 
i 


| CZCTC 


| TERMINAL TASK CONTROL 

| MTT COMMAND 

| FINDQ MACRO 

| READQ MACRO 

! WRITEQ MACRO 

1 CLEARQ MACRO 

| FREEQ MACRO 


CZCTCC 


CZCTCP 


I 

| CZCTC 1 

1 

| CZCTC 1 1 

! 

| CZCTC 2 

1 

| CZCTC 3 

1 

| CZCTC ^ 

1 

j CZCTC 5 

i 

i CZCTC 6 


RA 


i 

1 

i 

i 
; 

i 

i 
l 

! 

1 

1 


| CZCWA 


| ASCII TRANSLATION AND 
CONVERSION 


' CZCWAC 


CZCWAP 


j CZCWA1 


GE 
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1 


| CZCWB 


| BUILD OR MODIFY COMMON 
| PORTION OF A DEB 


CZCWBC 


CZCWBP 


| CZCWB1 

1 


AE 


i 
I 

! 

i 


| CZCWC 


| SAM CLOSE 


CZCWCC 


CZCWCP 


| CZCWC1 

1 


DB 


1 

1 
1 
i 


| CZCWD 


| DAOPEN 


CZCWDC 


CZCWDP 


1 

| CZCWDP 

i 


AD 


i 

i 


| CZCWL 


| BUILD OR EXTEND DA DEB 


CZCWLC 


CZCWLP 


1 

| CZCWL1 

t 


AF 


i 
1 

j 


! CZCWM 


| MESSAGE AND ABEND PROCESSING 


CZCWMC 


CZCWMP 


I 

i CZCWMl 


IC 


1 

i 


1 czcwo 


| SAM OPEN MAINLINE 


CZCWOC 


CZCWOP 


1 

| CZCWO 1 

1 


AB 


i 

1 
i 


( CZCWP 


| TAPE POSITIONING 


CZCWPC 


CZCWPP 


I 

| CZCWP1 

f 


IA 


i 

i 


1 CZCWR 


| READ FORMAT- 3 DSCBs 


CZCWRC 


CZCRWP 


1 

| CZCRWP 

i 


AG 


I 
1 


1 czcwrr 


| OPEN TAPE 


CZCWTC 


CZCWTP 


1 

j CZCWT1 

i 


AC 


1 


I czcwv 

L . .. J 


| VOLUME SEQUENCE CONVERT 
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czcwvc 
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CZCWVP 
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1 
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i 
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ID 


-T" 
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Module Name | CSECT 
TAPE VOLUME LABEL PROCESSOR | CZCWXC 




PSECT 


-+- 


. 1 

Entry | 
Points j 

CZCWX1 i 
C2CWX2 | 
CZCWX3 


, -..- - 1 

Chart ID | 
EA | 


czcwx 


CZCWXP 


i 
1 

: 
i 
t 

I 


CZCWY 




TAPE DATA SET LABEL PROCESSOR | CZCWYC 




CZCWYP 




CZCWY1 
CZCWY 2 
CZCWY3 
CZCWYC 


EB | 


1 

i 
I 


CZCXD 




DA OUTPUT EOV | CZCXDC 




CZCXDP 




CZCXD1 


FF | 


I 

1 
l 


CZCXE 




MAINLINE EOV ] CZCXEC 




CZCXEP 




CZCXE1 


FB | 


1 

1 
I 


CZCXI 




DA INPUT EOV | CZCXIC 




CZCXIP 




CZCXI1 


FE f 


1 

I 
i 


CZCXN 




DA INPUT LABEL PROCESSOR | CZCXNC 




CZCXNP 




CZCXN1 


EG j 


1 


CZCXO 




TAPE OUTPUT EOV | CZCXOC 




CZCXOP 




CZCXOl 


FD | 


s 

! 


CZCXS 




SET DSCB | CZCXSC 




CZCXSP 




CZCXS 1 


AH ! 


I 

i 


CZCXT 




TAPE INPUT EOV | CZCXTC 




CZCXTP 




CZCXT1 


FC | 


1 

I 
i 


CZCXU 




DA OUTPUT LABEL PROCESSOR [ CZCXUC 




CZCXUP 




CZCXU 1 


EH J 


a 

1 

i 


czcxx 




CONCATENATION PROCESSOR | CZCXXC 




CZCXXP 




CZCXX1 


FG | 


* 

1 
I 


CZCYA 




TAM OPEN t CZCYA 




CZCYAP 




CZCYA1 


AK | 


1 

1 

i 


CZCYG 




TAM CLOSE | CZCYG 




CZCYGP 




CZCYG1 


DE | 


1 

I 
i 


CZCYM 




TAM READ/WRITE I CZCYM 




CZCYMP 




CZCYM1 


BD | 


1 


CZCZA 


_A_ 


TAM POSTING | CZCZA 


_X_ 


CZCZAP 


-JL- 


CZCZA1 

,„« J 


1 CD | 
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APPENDIX D: QWKAR DSECT AND DESCRIPTION 



QWKAR 


DSE( 


QWKLEN 


DC 


QWKBKL 


DS 


QWKFRL 


DS 


QWKS14 


DS 


QWKS1S 


DS 


QWKSVO 


DS 


QWKSV1 


DS 


QWKSV2 


DS 


QWKSV3 


DS 


QWKSV4 


DS 


QWKSV5 


DS 


QWKSV6 


DS 


QWKSV7 


DS 


QWKSV8 


DS 


QWKSV9 


DS 


QWKS10 


DS 


QWKS11 


DS 


QWKS12 


DS 


QWKS13 


DS 


QWKRES 


DS 


QWKSTL 


EQU 


QWKCIP 


EQU 


DECB1 


EQU 




DS 


DECB2 


EQU 




DS 


DECB3 


EQU 




ORG 




DS 


QWKBKC 


DS 


QWKRE2 


DS 


QWKGRO 


DS 


QWKGR1 


DS 


QWKGR2 


DS 


QWKGR3 


DS 


QWKGR4 


DS 


QWKGR5 


DS 


QWKGR6 


DS 


QWKGR7 


DS 


QWKWK1 


DS 


QWKWK2 


DS 


QMKWK3 


DS 


QWKWK<t 


DS 


QWKWK5 


DS 


QWKWK6 


DS 


QWKWK7 


DS 


QWKWK8 


DS 


QWKLNK 


DS 


QWKEND 


EQU 


QMKSZ 


EQU 



QWKAR length 

Storage for backward link register 

Storage for forward link register 

Storage for Register 14 

Storage for Register 15 

Storage for Register 

Storage for Register 1 

Storage for Register 2 

Storage for Register 3 

Storage for Register 4 

Storage for Register 5 

Storage for Register 6 

Storage for Register 7 

Storage for Register 8 

Storage for Register 9 

Storage for Register 10 

Storage for Register 11 

Storage for Register 12 

Storage for Register 13 

NOTE ~ Reserved word number 1 

SETL in progress flag 

CLOSE in progress flag 



CDECSZ is defined within CHADEC as 
the size of the DECB) 



Block count of current volume 
NOTE ~ Reserved word number 2 



A (QWKSZ) 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

X'HO' 

X f 80' 

OF 
DECB1+DECSZ 

OF 

DECB2+DECSZ 
DECB3+DECSZ 
of 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

11F 

* 

QWLEND-- QWKLEN 

The QWK area consists of 340 bytes; DCBQWK contains its address. The first 19 words 
of the work area are the QSAM general register save area. The address of this save area 
is furnished to any called routine in the save area parameter register. These 19 words 
will have the same storage protection class as the one assigned to the data set. 

In the QWK work area, 36 words are used for the three DECBs used by QSAM. The first 
two DECBs (DECB1 and DECB2) are used for all the I/O operations. They are pointed to by 
the addresses in DCBDE1 and DCBDE2. All read or write operations will use the DECB 
pointed to by DCBDE2 , and all checking operations will use the DECB pointed to by DCBDE1. 
The addresses in DCBDE1 and DCBDE2 are switched after each read or write so that the 
check will refer to the current DECB. The third DECB (DECB3) holds the appropriate copy 
of one of the other DECBs if a transfer to the user f s SYNAD must be made. This copy is 
made so the user cannot erroneously alter the original DECB, The address of DECB3 is 
contained in DCBDE3. 



Save for (0) 

Save for (1) 

Save for C2> 

Save for C3) between subsections 



between subsections 
between subsections 
between subsections 



Save for (*4> 
Save for (5) 
Save for (6) 
Save for (7) 
Working area 
Register save area 
Register save area 
Register save area 
Register save area 
Register save area 
Register save area 
Working area 



between subsections 
between subsections 
between subsections 
between subsections 
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APPENDIX fc; DESCRIPTION OF FIELDS IN QSAM PORTION OF DC B 



This discussion will not attempt to cover tho.se fields used by QSAM which belong to 
the common portion of the DCB. 



FIELD DISPLACEMENT FROM ZERO (in h exadecimal) , QSAM USAGE 



DCBRCD 90 
DCBEAD 94 
DCBLX 98 

DCBLXN 9C 

DCBBSV 9E 

DCBLAD AO 

DCBDE1 A4 

DCBDE2 A8 

DCBDE3 AC 

DCBBF1 BO 

DCBBF2 B4 

DCBBF3 B8 

DCBLRS BC 
DCBSVL BE 

DCBQWK CO 

DCBQFO C4 

DCBQF1 CS 

DCBWFL 
DCBEOB 
DCBPTX 
DCBCPS 

DCBSW1 

DCBLM 

DCBSYN 

DCBAAC 



Address of the current logical record within the current block CI word) 

Address of the end of the current block (1 word) 

The complete TTRZ direct address of ZZCC i?\agnetic tape retrieval address 
to be used by SETI (4 bytes) 

Logical record count in the last block processed, used by SETL to retri- 
eve a particular logical record within a block (2 bytes) 

Save area for original contents of DCBBLK (2 bytes) 

Address of the first byte of the last logical record processed (1 word) 

Address of DECB1 (1 word) 

Address of DECB2 (1 word) 

Address of DECB3 (1 word) 

Address of data buffer initially assigned to DECB1 (1 word) 

Address of data buffer initially assigned to DECB2 (1 word) 

Address of data buffer used for a data set opened for RDBACK with vari- 
able format records (1 word) 

Save area for original contents of DCBLRE (2 bytes) 

Length of next logical record for variable format records in a readback 
data set 

Address of the QSAM work area (1 word) 

Reserved for QSAM (1 byte) 

Field containing the following QSAM flags (1 byte) : 

Set on to indicate TREOV issued a write request (bit 0) 

Set on to indicate an end-of-buf f ei condition (bit 1) 

Set on by PUTX to indicate a PUTX update was issued (bit 2) 

Set on to indicate to SETL that when a POINT is issued, the relative 
address should not be incremented by one (bit 3) 

Set on after the INITIO subsection is executed for the first time 
(bit 4) 

Set on when a locate-raode GET or PUT is issued (bit 5) 

SET ON WHEN SYNAD determines that a block is to be skipped (bit 6) 

Set on when SYNAD determines that an erroneous block is to be 
accepted (bit 7) 
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DCBQF2 C6 



Field containing the following QSAM flags (1 byte) : 



DCBLSW Set on to indicate to GET that SETL is specified in DCBMCD (bit 0) 

DCBSGB Set on to indicate that single buffering must be done (bit 1) 

DCBDNN Set on by PUT to indicate to BSAM READ/WRITE that a channel nine 
overflow test should be made (bit 2) 

DCBDET Set on by PUT to indicate to BSAM READ/WRITE that a channel twelve 
overflow test should be made (bit 3) 

DCBQF3 C7 Save area for the contents of the DCBOPI field used by SETL (1 byte) 
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INDEX 



Where more than one page reference is 
given, the major reference is first. 



ABEND 

exit from routine (see specific routine) 

interlock release 142-143 

processing for BSAM 93-94 
abnormal end termination (see ABEND) 
abnormal termination 54-59 
abort flag 64 

access dependent open processing 136 
access method phases 4-5 

Close 5 

Open 4 

Posting 4-5 

Read/Write 4 
add data set or member entries to 

SDST 111,116-117 
Add Directory Entry routine 
CCZCPD 162-163 

chart 398-399 
add member or alias descriptor 168 
ADE (Add Directory Entry) routine 
CCZCPD 162-163 

chart 398-399 
alias descriptor entry in POD 167 
allocate virtual storage algorithms 20-21 
alternate path retries 47,48 
ASCII interface in BSAM 7 
ASCII translation and converstion routine 
(CZCWA) 86-87 

chart 321-323 
assign pages to data set 110 
asynchronous interrupt routines 10 
ATCS macro use 195 
attention flag 64 



Backspace 149 

Backspace CBSP) routine (CZCRG) 85-86 

chart 319 
Basic Sequential Access Method 

construct channel program 28 

introduction 3 

IOCAL use 28-30 

modules invoked by QSAM 177 

overview 7-8 

routines (see specific routine) 

special routines 74-95 
beginning 149 

blocking factors for MSAM 9 
blocking logical records 18 2 
BREAK operand of TAM Write 40 
BSAM Csee Basic Sequential Access Method) 
BSAM Read/Write routine (CZCRA) 28 

chart 223-226 
BSP (Backspace) 

chart 319 

macro instruction 6 

routine (CZCRG) 85-86 



buffer allocation flag 42 

buffer area 4 4 

buffer page 8 

buffer size computation 

BSAM 86 

MSAM 9 

TAM 62 
buffer specification 62 
buffering 86 

buffering, single or double 183-185 
BUFTEK 62 
Build Common DEB routine (CZCWB) 17 

chart 210 
Build DA DEB routine (CZCWL) 18 

chart 211 
building and maintaining a VAM data 

set 119 
building the RESTBL 135 
bus out check 

DA 52 

MSAM 

printer 55,57-59 

reader, punch 54-55,56-57 

2400 tape 48 



card punch configuration specification 
carriage return 62 
catalog entry release 124 
CCW 

BSAM 29 

IOREQ 41 

MSAM 34 

TAM 36 

TAM CCW trace list 61 
CHADCB 109 

CHADHD (DCB header) 111-113 
CHAEPE (external page entries) 111 
chaining 44 
chaining check 

DA 52 

2400 series tape 50 
CHAISA (interrupt storage area) 108 
CHAMHD (member headers) 111 
channel command word (see CCW) 
channel control check 56 
channel data check 

MSAM 56 

2311, 2314, 2302 51 
channel end 61 
channel failure 60 
channel program 

BSAM Read/Write 28 

DA Write 29 

MSAM 33 
channel program generator 36, 38 
channel program index table 38 
CHARHD (RESTBL header) 113 
CHATDT (task data definition table) 108 
check (and posting) processing 46-67 
Check routine (CZCRC) 66 

chart 278 



21 



456 



check subroutine 186 
CLEARQ macro processor 197 
Close 

BSAM overview 7 

duplicate DCB 141 

final processing 1 MO 

last open DCB 140 

module interaction Hi 

phase 5 

processing 68-73 

QSAM 190 

SAM 6 8 

TAM Close routine 72 

VAM 139 

VISAM 142 

VSAM 142 
Close Common routine (CZCLB) 68 

chart 281 
close temporary 140 
CLOSEVAM routine (CZCOB) 139 

chart 369 
closing last open DCB 140 
CNTRL (see Control) 
code generator storage parity error 

error 58 
COMBIN option 7 
command reject 

DA 53 

MS AM 

printer 58 
reader, punch 57 

2400 tape 49 
Common Close (see Close Common) 
Common Open (see Open Common) 
comparison of access methods routines 3 
completion of I/O 7-8 

concatenation of record to data set 101 
Concatenation routine (CZCXX) 83 

chart 316 
CONN SVC, use in MTT 196 
Construct (subroutine of BSAM 

Read/Write) 28 
control clock relationship 115 
control blocks 

access methods area 5 

QSAM 178 

relationship 115 

SAM, TAM, IOREQ 5-7 

user area 5 

VAM 107-113 

VISAM 152 

VPAM 164 
Control routine (C2CRB) 86 

chart 319 
control table interlocks 128 
CPG (channel program generator) 36,38,40 
CPIT (channel program index table) 40 
CSW zero S6 
cylinder end 53 
CZCEI (Virtual Memory Input Error 

Recorvery) 102 ,340 
CZCEY (DUPOPEN) 136,366 
CZCEZ (DUPCLOSE) 141,374 
CZCFT (Delete a VAJ4 Data Set) 124,356 
CZCLA (Open Common) 14,200 
CZCLB (Close Common) 68,281 
CZCLD (Force End of Volume) 79,309 
CZCMA (GETBUF) 89,325 



CZCMB (GETPOOL) 87,324 

CZCMC (KSAM Open) 19,214 

CZCMD (Set Unit Record) 21,216 

CZCME (DOMSAM) 30,227 

CZCMF (Read/Write, MSAM) 34,237 

CZCMG (MSAM Postinq) ^4,264 

CZCMIl (MT.AM Finish) 6 l >,284 

CZCMI (MSAM Clot.t-) 71,289 

CZCNA (FREEBUF) 90,326 

CZCNB (FREEPOOL) 90,327 

CZCOA (OPENVAM) 132,361*- 

CZCOB (CLOSEVAM) 139,369 

CZCOC (MOVEPAGE) 98,336 

CZCOD (Insert/Delete Page) 119,351 

CZCOE (Request External Pages) 122,354 

CZCOF (Insert) 120,352 

CZCOG (Reclaim) 123,355 

CZCOH (Interlock) 129,359 

CZCOI (Release Interlock) 130,360 

CZCOJ (Find) 165,400 

CZCOK (Stow) 168,404 

CZCOL (Search) 171,412 

CZCOM (Extend POD) 172,413 

CZCON (Relocate Members) 172,414 

CZCOO (GETNUMBR) 173,415 

CZCOP (VAM Open) 137,367 

CZCOQ (VAM Close) 142,375 

CZCOR (VSAM GET) 144,379 

CZCOS (VSAM PUT) 147,381 

CZCOT (VSAM SETL) 148,383 

CZCOU (PUTX) 150,385 

CZCOV (FLUSHBUF) 150,386 

CZCPA (VISAM PUT) 155,387 

CZCPB (VISAM GET) 157,390 

CZCPC (VISAM SETL) 157,392 

CZCPE (Read/Write Delete Record) 159,394 

CZCPI (GETPAGE) 160,396 

CZCPL (Add Directory Entry) 162,398 

CZCPZ (VISAM Open) 138,368 

CZCQA (VISAM Close) 142,376 

CZCQE (Search SDST) 112,348 

CZCQI (Expand RESTBL) 121,353 

CZCQK (VAM Data Management Error 

Processing) 104,343 
CZCQQ (VAM ABEND Interlock 

Release) 142,377 
CZCRA (BSAM Read/Write) 28,223 
CZCRB (Control) 28,223 
CZCRC (Check) 86,320 
CZCRG (Backspace) 85,319 
CZCRH (DA Error Recovery) 50,257 
CZCRM (Point) 84,318 
CZCRN (Note) 83,317 
CZCRP (Posting, BSAM) 46,245 
CZCRQ (FINDR) 94,333 
CZCRR (RELFUL) 95,334 
CZCRS (FULREL) 95,335 
CZCSA (QSAM) 179,417 
CZCSB (IOREQ) 41,244 
CZCSC (I/O Request, Open) 26,222 
CZCSD (I/O Request, Close) 73,292 
CZCSE (Posting, IOREQ) 65,277 
CZCTC (Terminal Task Control) 195,433 
CZCWA (ASCII Translation and 

Conversion) 86,321 
CZCWB (Build Common DEB) 17,210 
CZCWC (SAM Close) 68,282 
CZCWD (DA Open, BSAM) 17,208 
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78,307 



78,308 
83,316 



CZCWL (Build DA DEB) 18,211 

CZCWM (Message Writer) 93,332 

CZCWO (SAM Open) 15,202 

CZCWP (Tape Positioning) 91,328 

CZCWR (Read Format- 1 DSCBs) 19,212 

CZCWT (TAPE OPEN) 16,206 

CZCWV (Volume Sequence Convert) 92,331 

CZCWX (Tape Volume Label) 74,294 

CZCWY (Tape Data Set Label) 7**, 298 

CZCXD (DA Output EOV) 82,314 

CZCXE (Mainline EOV) 79,310 

CZCXI (DA Input EOV) 82,313 

CZCXN (DA Input Label Processor) 

CZCXO (Tape Output EOV) 81,312 

CZCXS (Set DSCB) 19,213 

CaCXT (Tape Input x.OV) 80,311 

CZCXU (DA Output Label Processor) 

CZCXX (Concatenation Processor) 

CZCYA (TAM Open) 24, 221 

CZCYG (TAM Close) 72,291 

CZCYM (TAM Read/Write) 35,242 

CZCZA (TAM Posting) 60,275 



DA Error Recovery routine (CZCRH) 50 

chart 257 

contingent processing 51-54 

general processing 50 
DA Input EOV routine (CZCXI) 52 

chart 313 
DA Input Label Processor routine 
(CZCXN) 78 

chart 307 
DA Open routine (CZCWD) 17 

chart 208 
DA Output EOV routine (CZCXD) 82 

chart 314 
DA Output Label Processor routine (CZCXU) 78 

chart 308 
DA Read/Write (see BSAM Read/Write) 27 
DAIN (DA Input EOV) routine (CZCXI) 82 

chart 313 
DAOV (DA Output EOV) routine (CZCXD) 82 

chart 314 
data check 

MS AM 

printer 56 
reader, punch 57 

2311, 2314. 2302 51 

2400 tape 49 
Data Control Block 

primary /secondary 136 

QSAM 178 

SAM, TAM, EOREQ 5 

VAM 109 

VISAM 152 

VSAM 145 
data converter check 49 
Data Event Control Block 

check (interceptions) 66 

IOT*EQ 4 2 

MSAM 11,34 

QSAM 178 

queue (IOREQ) 42 

SAM 28 

VISAM 152 • 
Data Extent Block 

building of 



common 1 7 
DA 18 
SAM 15 
tape 16 

DA size algorithm 18 

modify 18 

page and workpage layout 20 

processing 18 

QSAM 178 

SAM 6 
data group f 9-71, 8 
data movement from buffer 42-45 
Data Set Control Block 

Read Format- 3 DSCB 19 

SAM processing 19 

Sr.T DSCB 19 

VAM 118 
data set labels 74-79 
data set maintenance 119-126 
data set page release 125 
data set sharing 127-131,102,112-117 
DCB (see Data Control Block) 
DCB header 112 

chaining of 135 

interlock summary 143 
DCB macro, control block building 3 
DCBD macro, control block building 3 
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